# Testing Foundations

Bootgly has two testing APIs, a Basic API and an Advanced API. Before implementing cases, start with file structure, suites, test case APIs and visual separators.

## Structure of test files and directories

Tests implemented in each module should be placed inside a same-level directory named `tests`. In each `tests` directory, there should be a suite bootstrap file named `autoboot.php`. Files that implement test cases live inside the `tests` directory and follow the `*.Test.php` pattern.

You can define any test case file name, but following the existing pattern is recommended. A real example is `1.01-request_as_response-address.Test.php`.

### Directory + files

```txt
tests
└── autoboot.php  # Bootstrap file for the suite
└── 1.1-some_case-part1.Test.php  # Test Case file
└── 1.2-other_case-part2.Test.php  # Test Case file
└── 2.1-another_case.Test.php  # Test Case file
...
```

### Visual diagram

```txt
Test Suite
└── Test Case
    └── Assertions
        ├── Assertion
        └── Assertion
        ...
└── Test Case
    └── Assertions
        ├── Assertion
        └── Assertion
```

### Overview

```txt
tests
└── autoboot.php  # Bootstrap file for the suite
└── 1.1-some_case.Test.php  # Test Case files
    └-- Assertions
       ├-- Assertion
       └-- Assertion
```

## Test suite

Every bootstrap file that defines a test suite follows a standard structure.

```php
<?php

# namespace here

use Bootgly\ACI\Tests\Suite;

return new Suite(
   // * Config
   autoBoot: __DIR__,
   autoInstance: true,
   autoReport: true,
   autoSummarize: true,
   exitOnFailure: true,
   // * Data
   suiteName: __NAMESPACE__,
   tests: [
      '1.0-name' // the suffix ".Test.php" should be omitted
   ]
);
```

Real example of a test suite defined in Bootgly:

```php
<?php # Bootgly/ABI/Code/__String/tests/autoboot.php

namespace Bootgly\ABI\Code\__String;

use Bootgly\ACI\Tests\Suite;

return new Suite(
   // * Config
   autoBoot: __DIR__,
   autoInstance: true,
   autoReport: true,
   autoSummarize: true,
   exitOnFailure: true,
   // * Data
   suiteName: __NAMESPACE__,
   tests: [
      '1.x-dynamic-props-length',
      '1.x-dynamic-props-lowercase',
      '1.x-dynamic-props-pascalcase',
      '2.x-dynamic-methods-pad',
      '2.x-dynamic-methods-search',
   ]
);
```

### A suite driven by its own `autoBoot`

`autoBoot` also takes a closure: the suite then runs its own lifecycle — the live E2E suites start a server and drive their cases through it. Whatever drives the cases, a suite that lists cases and ends with **none of them run or recorded** fails the run with `The autoBoot of "<suite>" returned without running or recording any of its cases.` A case it skips on purpose (`$Suite->skip(...)`) counts as recorded; a case only settled as "not reached" does not. A harness that never reached its server can never pass as an empty green suite.

## Test cases

Test case files have two main structures: one for the Basic API and another for the Advanced API.

### Basic API structure

```php
<?php

use Bootgly\ACI\Tests\Suite\Test;

return new Test(
   description: 'Description of the test case here',
   test: function (): string|bool|null
   {
      // implement assertions here
   }
);
```

### Advanced API structure

```php
<?php

use Bootgly\ACI\Tests\Assertion;
use Bootgly\ACI\Tests\Assertions;
use Bootgly\ACI\Tests\Suite\Test;

return new Test(
   description: 'Description of the test case here',
   test: new Assertions(Case: function (): Generator
   {
      // implement assertions here
   })
);
```

## Visual Separators

Use the `Separator` class to organize test output with visual separators from the basic `Test` structure.

```php
use Bootgly\ACI\Tests\Suite\Test\Separator;

return new Test(
   Separator: new Separator(
      line: 'Section Name',    // Separator line with label
      left: 'Category',        // Left-side label
      header: 'Main Section',  // Section header
   ),
   description: 'Test case',
   test: function (): bool
   {
      return true;
   }
);
```

| Property | Type | Description |
| -------- | ---- | ----------- |
| `line` | `bool\|string\|null` | Separator line. Use `true` for a simple line or `string` for a label. |
| `left` | `string\|null` | Label displayed on the left. |
| `header` | `string\|null` | Section header. |
