Pest

https://github.com/pestphp/pest
Admin
Pest is an elegant PHP testing Framework with a focus on simplicity, meticulously designed to bring...
Tokens:234,425
Snippets:1,487
Trust Score:8.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### fixture() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Shows how to use `fixture()` to get the path to a fixture file and then read its contents.

```php
$p = fixture('users/alice.json');

expect(file_get_contents($p))->toBeJson();
```

--------------------------------

### Install dev dependencies with composer install

Source: https://github.com/pestphp/pest/blob/5.x/CONTRIBUTING.md

Installs the development dependencies after cloning the fork.

```bash
composer install
```

--------------------------------

### beforeAll() and afterAll() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example usage of the `beforeAll()` and `afterAll()` functions. Registers hooks to run once before and after all tests in the file.

```php
beforeAll(function () {
    database()->migrate();
});

afterAll(function () {
    database()->drop();
});
```

--------------------------------

### dataset() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example of registering a named dataset and using it in a test with the with() method.

```php
dataset('users', [
    ['Alice', 42],
    ['Bob', 17],
]);

test('ages', function (string $name, int $age): void {
    expect($age)->toBeInt();
})->with('users');
```

--------------------------------

### dump() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example of using dump() to output the value and then continue with a toBeArray() assertion.

```php
expect($payload)->dump()->toBeArray();
```

--------------------------------

### UsesCall usage examples

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/describe-and-hooks.md

Examples of using pest() and uses() to bind classes/traits, apply groups, and register hooks scoped to specific directories.

```php
pest()
    ->extend(MyFeatureTestCase::class)
    ->in('Feature');

uses(\App\Testing\RetryAll::class)->group(['retryable']);

pest()->in('Unit')->beforeEach(fn () => $this->enableFeatures());
```

--------------------------------

### group() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Usage example for group(). Assigns the test to the 'integration' group.

```php
test('integration path', function (): void {
    // ...
})->group('integration');
```

--------------------------------

### visit() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example usage of the `visit()` function to navigate to a URL in a browser test. This is a simple call with a single URL string.

```php
visit('https://example.com');
```

--------------------------------

### toStartWith

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Asserts that the string value starts with the expected substring using assertStringStartsWith.

```APIDOC
## toStartWith

### Description
Asserts that the string value starts with the expected substring using assertStringStartsWith.

### Method
N/A (Matcher method)

### Endpoint
N/A

### Parameters
#### Method Parameters
- **$expected** (string) - Required - The expected prefix.
- **$message** (string) - Optional - Custom assertion message.

### Request Example
```php
expect('order-123')->toStartWith('order-');
```

### Response
#### Success Response
No return value; throws on failure.

#### Response Example
N/A
```

--------------------------------

### only() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Usage example for only(). Focuses the test so only that group runs.

```php
test('flaky one, focus me', function (): void {
    // ...
})->only();
```

--------------------------------

### describe() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example usage of the `describe()` function. Shows a describe block with a `beforeEach` hook and a test. The `beforeEach` hook is scoped to the describe block.

```php
describe('User feature', function () {
    beforeEach(function () {
        $this->user = new User;
    });

    test('works', function () {
        expect($this->user->isValid())->toBeTrue();
    });
});
```

--------------------------------

### Usage example with beforeEach, test, and describe

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/describe-and-hooks.md

Shows how to use beforeEach to set up a user, a test that uses it, and a describe block with scoped covers.

```php
beforeEach(function () {
    $this->user = new User;
});

test('uses user', function (): void {
    expect($this->user)->toBeInstanceOf(User::class);
});

describe('inside describe', function () {
    beforeEach()->covers('App\Services\Mailer');

    test('scoped covers', function (): void {
        // ...
    });
});
```

--------------------------------

### Chained test call example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Example of chaining visit and post methods on a test to demonstrate dynamic chain recording.

```php
test()->visit('https://example.com')->post('/login', ['user' => 'a']);
```

--------------------------------

### covers() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example of using covers() to declare that the test file covers a specific class.

```php
covers('App\Services\Invoice');

test('totals the invoice', function (): void {
    // ...
});
```

--------------------------------

### Standard Pest.php bootstrap

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Standard bootstrap example from stubs/init/Pest.php. Shows how to extend a test case, set a GitHub project, and enable compact printer output.

```php
// stubs/init/Pest.php — standard bootstrap
pest()->extend(TestCase::class)->in('Feature');

pest()->project()->github('acme/app');

pest()->printer()->compact();
```

--------------------------------

### depends() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Usage example for depends(). The test runs only after the 'logs in' test passes and receives its return value as an argument.

```php
test('creates order', function (): int {
    return createOrder();
})->depends('logs in');
```

--------------------------------

### Basic it() usage

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example of using `it()` to define a test with a dataset via `with()`.

```php
it('returns a greeting', function (): string {
    return greet('Pest');
})->with(['Pest']);
```

--------------------------------

### Using todo and wip in tests

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Usage examples for todo and wip. todo marks a test as skipped with metadata, while wip applies metadata without skipping.

```php
todo('support refunds', note: 'needs gateway', assignee: 'amanda');

test('actual feature', function (): void {
    // ...
})->wip(issue: 123, pr: 456);
```

--------------------------------

### dd() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example of using dd() to dump and die with an expectation value.

```php
expect($user)->dd();
```

--------------------------------

### pest() usage examples

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example usage of the pest() function to extend a test case and set the project's GitHub repository.

```php
pest()->extend(TestCase::class)->in('Feature');
pest()->project()->github('acme/app');
```

--------------------------------

### Kernel boot and handle usage in bin/pest

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/runtime-kernel.md

Shows the internal usage of the `Kernel` class from `bin/pest`. Boots the kernel with the test suite and input/output, handles the arguments to get an exit code, terminates, and exits with that code.

```php
// Internal usage (bin/pest):
$kernel = Kernel::boot($testSuite, $input, $output);
$result = $kernel->handle($originalArguments, $arguments);
$kernel->terminate();
exit($result);
```

--------------------------------

### Only and group usage

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Non-trivial example showing how to focus the current file with only() and then target the 'Feature' directory with the 'feature' group.

```php
pest()->only();               // run only this file's tests
pest()->in('Feature')->group('feature');
```

--------------------------------

### String matching with toStartWith, toEndWith, and toMatch

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Use toStartWith to assert a string starts with a given substring, toEndWith for ending substring, and toMatch for regular expression matching. All require string values; non-string values throw InvalidExpectationValue::expected('string').

```php
expect('order-123')->toStartWith('order-');
expect('ab12cd')->toMatch('/\d{2}/');
```

--------------------------------

### todo() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example usage of the `todo()` function. Registers a test marked as todo, which will be skipped.

```php
todo('handle pagination edge case');
```

--------------------------------

### visit()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Browser testing entry point that visits a URL or list of URLs. Requires the pestphp/pest-plugin-browser plugin. If the plugin is not loaded, it installs it and restarts Pest; otherwise, it delegates to test()->visit().

```APIDOC
## visit()

### Description
Browser testing entry point that visits a URL or list of URLs. Requires the pestphp/pest-plugin-browser plugin. If the plugin is not loaded, it installs it and restarts Pest; otherwise, it delegates to test()->visit().

### Method
Function call

### Signature
```php
function visit(array|string $url, array $options = []): ArrayablePendingAwaitablePage|PendingAwaitablePage
```

### Parameters
- **$url** (array<string>|string) - Required - URL (or list of URLs) to visit
- **$options** (array<string, mixed>) - Optional - Browser options forwarded to TestCall::visit. Default: []

### Return Value
- **ArrayablePendingAwaitablePage|PendingAwaitablePage** - The pending page object for further assertions.

### Example
```php
visit('https://example.com');
```
```

--------------------------------

### toThrow usage examples

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Shows how to use toThrow with no argument, with an exception class, and with a closure that receives the caught exception.

```php
expect(fn (): void => strToUpper(null))->toThrow();
expect(fn (): void => strToUpper(null))->toThrow(\Error::class);

// closure parameter typed as the exception class:
expect(fn (): void => throw new LogicException('nope'))
    ->toThrow(fn (LogicException $e): void => {
        expect($e->getMessage())->toBe('nope');
    });
```

--------------------------------

### with() usage example with chained dataset

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Usage example for with() with an inline array dataset and a chained named dataset 'formats'. The test receives $name and $expected from the dataset.

```php
test('formats names', function (string $name, string $expected): void {
    expect(format($name))->toBe($expected);
})->with([
    ['pest', 'PEST'],
    ['php', 'PHP'],
])->with('formats');  // chained dataset
```

--------------------------------

### fixture() error handling example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Shows how to catch the `InvalidArgumentException` thrown by `fixture()` when the file does not exist.

```php
try {
    fixture('missing.json');
} catch (InvalidArgumentException $e) {
    // "The fixture file [...missing.json] does not exist."
}
```

--------------------------------

### each() usage examples

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Shows two ways to use `each()`: applying an assertion to every item, and using a callback that receives an `Expectation` per item and the key.

```php
expect([1, 2, 3])->each()->toBeInt();

expect(['ab', 'cd'])->each(function (Expectation $item, string $key): void {
    $item->toHaveLength(2);
});
```

--------------------------------

### match() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example usage of match() with a literal subject and callable expressions. The subject 'status' is matched against the keys 'ok' and 'error', and the corresponding callable receives an Expectation instance to assert the value.

```php
expect(42)->match('status', [
    'ok' => fn (Expectation $v): void => $v->toBe(200),
    'error' => fn (Expectation $v): void => $v->toBe(500),
]);
```

--------------------------------

### when() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example usage of when() with a boolean condition and a callback that asserts the value is greater than 0. The callback receives an Expectation instance.

```php
expect($tax)->when($region === 'EU', fn (Expectation $v): void => $v->toBeGreaterThan(0));
```

--------------------------------

### Registering beforeEach() and afterEach() hooks

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example of registering beforeEach() and afterEach() hooks to set up and tear down a user for every test in the current scope. The test then uses the seeded user via $this->user.

```php
beforeEach(function () {
    $this->user = UserFactory::make();
});

afterEach(function () {
    $this->user->delete();
});

test('uses the seeded user', function () {
    expect($this->user->id)->toBeInt();
});
```

--------------------------------

### Pest\Preset

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-arch.md

Documentation for the Pest\Preset class, including its methods, usage examples, custom preset registration, and exceptions.

```APIDOC
## `Pest\Preset`

### Description
Provides access to built-in architecture presets and allows registering custom presets. Obtained via `$this->preset()` inside a test or through custom architecture setups.

### Methods

#### `php(): Php`
- **Description**: Registers the PHP preset expectations.

#### `laravel(): Laravel`
- **Description**: Registers the Laravel preset expectations.

#### `strict(): Strict`
- **Description**: Registers the strict preset expectations.

#### `security(): AbstractPreset`
- **Description**: Registers the security preset expectations.

#### `relaxed(): AbstractPreset`
- **Description**: Registers the relaxed preset expectations.

### Usage Example
```php
// in a test (Testable::$this):
test('architecture', function () {
    $this->preset()->php();
});
```

### Custom Presets
Register a custom preset from a bootstrap file using `pest()->presets()->custom()`.

```php
// custom preset registered from a bootstrap file (stubs/init/Pest.php):
pest()->presets()->custom('myteam', function () {
    $this->eachUserNamespace(
        fn (Expectation $namespace): ArchExpectation => $namespace->classes()->not->toBeAbstract(),
    );
});
```

### Exceptions
- **`Pest\Exceptions\InvalidArgumentException`**: Thrown when calling an unknown custom preset name via `__call` (message: `The preset [$name] does not exist. The available presets are [...]`).
- **`Pest\Exceptions\InvalidArgumentException`**: Thrown when registering a custom preset whose name contains anything other than `a-z`/`A-Z` (message: `The preset name must only contain words from a-z or A-Z.`).
```

--------------------------------

### Using Pest\testDirectory()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Imports and calls Pest\testDirectory() to get the path for 'Fixtures/user.php' relative to the test directory.

```php
use function Pest\testDirectory;

$fixturePath = testDirectory('Fixtures/user.php');
```

--------------------------------

### Container class public methods

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Public API of the Container class: getInstance() returns the singleton, get() resolves a dependency by id, and add() registers an instance. The get() method builds unregistered dependencies via constructor reflection and throws Pest\Exceptions\ShouldNotHappen on failure.

```php
public static function getInstance(): self                       // L23
public function get(string $id): object|string                   // L32
/**
 * @return $this
 */
public function add(string $id, object|string $instance): self   // L45
```

--------------------------------

### Example usage of skip modifiers

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Example test cases using onlyOnWindows(), skipOnCI(), and skipOnPhp() to conditionally skip tests based on OS, CI environment, or PHP version.

```php
test('windows-only rendering', function (): void {
    // ...
})->onlyOnWindows();

test('never on CI', function (): void {
    // ...
})->skipOnCI();

test('php 8.3+ only', function (): void {
    // ...
})->skipOnPhp('<=8.2');
```

--------------------------------

### Initialize Pest test suite

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/cli-plugins.md

Scaffolds the initial Pest test directory structure. When laravel/framework is installed, Laravel-specific stubs are used. Existing files are reported and left untouched.

```bash
php bin/pest --init
```

--------------------------------

### fails() and throws() usage examples

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Usage examples for fails() and throws(). The first test expects failure with a message; the second expects an OverflowException with message 'too big' and code 422.

```php
test('rejects empty input', function (): void {
    // body that must fail
})->fails('input validation');

test('throws on overflow', function (): void {
    push(1_000_000);
})->throws(OverflowException::class, 'too big', 422);
```

--------------------------------

### Using not() with common matchers

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/opposite-each-higher-order.md

Examples of using the not() wrapper to assert the opposite of common matchers: toStartWith, toBeEmpty, and toHaveKeys.

```php
expect('hello world')->not->toStartWith('bye');
expect([1, 2])->not->toBeEmpty();
expect(['a' => 1])->not->toHaveKeys(['b']);
```

--------------------------------

### Pest\PendingCalls\BeforeEachCall

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/describe-and-hooks.md

Documentation for the BeforeEachCall class, including its constructor, methods, and usage example.

```APIDOC
## `Pest\PendingCalls\BeforeEachCall`

### Description
Represents a `beforeEach` hook registration. Returned by `beforeEach()` and used to chain additional setup or teardown logic.

### Constructor
```php
public function __construct(
    public readonly TestSuite $testSuite,
    private readonly string $filename,
    ?Closure $closure = null
)
```

#### Parameters
- **$testSuite** (`TestSuite`) - Required - Suite singleton.
- **$filename** (`string`) - Required - Declaring file.
- **$closure** (`?Closure`) - Optional - Hook body; `null` yields `NullClosure::create()`.

### Methods

#### `after(Closure $closure): self`
Registers a cleanup for the beforeEach-hook's test case. **Throws** `Pest\Exceptions\AfterBeforeTestFunction` when used outside a `describe` block.

#### `__call(string $name, array $arguments): self`
Forwards `TestCall` methods into `testCallProxies` (replay on every `TestCall`); everything else goes to `testCaseProxies` (replays on the generated test case).

### Example
```php
beforeEach(function () {
    $this->user = new User;
});

test('uses user', function (): void {
    expect($this->user)->toBeInstanceOf(User::class);
});

describe('inside describe', function () {
    beforeEach()->covers('App\Services\Mailer');

    test('scoped covers', function (): void {
        // ...
    });
});
```
```

--------------------------------

### Pest\Expectations\EachExpectation

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/opposite-each-higher-order.md

Documentation for the EachExpectation class, including its constructor, methods, and usage examples.

```APIDOC
## `Pest\Expectations\EachExpectation`

### Description
A higher-order expectation that applies assertions to each item of an iterable value. Created by calling `each()` on an `Expectation` when the value is iterable.

### Constructor
- `__construct(Expectation $original)` - Creates a new instance wrapping the original expectation.

### Methods
- `not(): self` - Returns a new instance with negation enabled for the next assertion.
- `and(mixed $value): Expectation` - Chains another expectation with a new value.
- `__call(string $name, array $arguments): self` - Applies the named matcher to each item of the original value. If `not()` was called, each item is negated. The opposite flag resets after each call.
- `__get(string $name): self` - Accesses a property on each item, returning a new instance for further assertions.

### Usage Example
```php
expect([1, 2, 3])->each()->toBeInt();
expect(['a', 'bb'])->each()->not->toHaveLength(3);

expect([[1], [2]])->each(function (Expectation $item): void {
    $item->each()->toBeInt();
});
```
```

--------------------------------

### Using uses() with ->in()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Example of using uses() to bind a test case class to the current test file and scope it to the 'Feature' directory via the ->in() method.

```php
uses(MyAppIntegrationTestCase::class)->in('Feature');
```

--------------------------------

### json() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example of using json() to assert a JSON string and then check for a key. The method decodes the JSON and returns an expectation for the decoded array.

```php
expect('{"ok": true, "n": 2}')->json()->toHaveKey('ok');
```

--------------------------------

### Using any() wildcard

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example usage of the any() wildcard to skip the value assertion for the 'id' property.

```php
expect($user)->toHaveProperty('id', expect($user->id)->any());
```

--------------------------------

### sequence() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Applies a sequence of callbacks to each item in the iterable, wrapping around if needed. Each callback receives an `Expectation` for the item.

```php
expect(['2010', '2011', '2012'])->sequence(
    fn (Expectation $year): void => $year->toBeStartWith('2010'),
    fn (Expectation $year): void => $year->toBeStartWith('2011'),
    fn (Expectation $year): void => $year->toBeStartWith('2012'),
);
```

--------------------------------

### not() usage examples

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Shows usage of `not()` to invert assertions. The first checks that a string does not start with 'bye', the second that an array is not empty.

```php
expect('hello')->not->toStartWith('bye');
expect([1, 2])->not->toBeEmpty();
```

--------------------------------

### Using not() with closure and property matchers

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/opposite-each-higher-order.md

Non-trivial examples of not() with a closure matcher (toThrow) and a property matcher (toHaveProperty) with an explicit failure message.

```php
expect(fn (): void => doSomething())->not->toThrow();
expect($result)->not->toHaveProperty('retries', 3);
```

--------------------------------

### Custom expectation with extend()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example of registering a custom expectation 'toBeEven' and using it. The closure is bound to the Expectation, and its return value becomes the result.

```php
use function Pest\expect;

expect()->extend('toBeEven', function (string $message = ''): self {
    return $this->and($this->value % 2)->toBe(0, $message);
});

expect(4)->toBeEven();        // passes
expect(3)->toBeEven();        // fails
```

--------------------------------

### Register and retrieve a token with Container

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Shows how to register a custom token with the container and retrieve it. The add() method accepts an object or string instance, and get() returns the resolved value cast to string.

```php
$container = Container::getInstance();
$container->add('my.token', computeToken());
$token = (string) $container->get('my.token');
```

--------------------------------

### Chaining metadata methods on a test

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Example of chaining metadata methods on a test definition to attach issue, PR, assignee, and note information.

```php
test('pr regression', function (): void {
    // ...
})->issue(142)->pr(57)->assignee('devops')->note('see #142 discussion');
```

--------------------------------

### Register a trait with Plugin::uses()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Example of a plugin package bootstrap that registers a trait to be applied to all generated test cases via Plugin::uses().

```php
// plugin package bootstrap
Plugin::uses(\MyPlugin\Testing\TestCaseTrait::class);
```

--------------------------------

### Show Pest help output

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/cli-plugins.md

Displays the version banner, usage, and the full option catalog, including Pest-specific additions. Exits with code 0 after rendering.

```bash
php bin/pest --help
```

--------------------------------

### Comparison matchers usage

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Example of using toBeBetween and toBeIn matchers. toBeBetween checks the value is between the given lowest and highest values (inclusive), toBeIn checks the value is a member of the given iterable.

```php
expect(10)->toBeBetween(5, 15);
expect('m')->toBeIn(['s', 'm', 'l']);
```

--------------------------------

### after() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Example usage of after() to run a cleanup closure after the test. The closure receives the running test case as $this.

```php
test('creates an invoice', function (): void {
    // ...
})->after(fn () => $this->cleanup());
```

--------------------------------

### Conditional chainable closure example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/opposite-each-higher-order.md

Shows how to create a chainable closure that conditionally runs a skip action when running in CI. Uses ChainableClosure::boundWhen with a condition checking the environment name and a closure that calls $this->skipOnCI().

```php
// condition-chained hook (BeforeEachCall internals use the same helper):
$conditional = ChainableClosure::boundWhen(
    fn (): bool => Environment::name() === Environment::CI,
    fn (): void => $this->skipOnCI(),
);
```

--------------------------------

### ddWhen() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example of using ddWhen() with a closure that checks the response status. The dump occurs only when the condition is true.

```php
expect($response)->ddWhen(fn (array $r): bool => $r['status'] > 500);
```

--------------------------------

### Pest\Configuration::__construct

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Creates a new Configuration instance. If the filename ends with `DIRECTORY_SEPARATOR.'Pest.php'`, the root is set to the directory of that file.

```APIDOC
## `Pest\Configuration::__construct`

### Description
Creates a new Configuration instance. If the filename ends with `DIRECTORY_SEPARATOR.'Pest.php'`, the root is set to the directory of that file.

### Method
`__construct(string $filename)`

### Parameters
- `$filename` (string) - Required - The filename of the configuration file.

### Example
```php
new Configuration('tests/Pest.php');
```
```

--------------------------------

### Using expect() with toBe and toContain

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Shows basic usage of expect() with toBe() and toContain() matchers.

```php
expect(1 + 1)->toBe(2);
expect(['a', 'b'])->toContain('b');
```

--------------------------------

### Tia plugin commands: --tia, --fresh, --baseline

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/cli-plugins.md

Commands for the Tia plugin: --tia enables mutation testing, --fresh records from scratch, and --baseline prints the storage directory to stdout.

```bash
php bin/pest --tia
```

```bash
php bin/pest --tia --fresh
```

```bash
php bin/pest --baseline
```

--------------------------------

### Pest\Configuration\Project::bitbucket()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Configures Bitbucket URL templates for issues and pull requests.

```APIDOC
## `Pest\Configuration\Project::bitbucket()`

### Description
Configures the project to use Bitbucket URLs for issues and pull requests.

### Method
`bitbucket`

### Signature
`public function bitbucket(string $project): self`

### Parameters
- **$project** (string) - Required - The Bitbucket project identifier.

### Returns
`self` - Returns the same instance for chaining.

### Effect
Sets the URL templates for issues and pull requests.
```

--------------------------------

### Dataset resolution shape example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/types.md

Example of the array shape returned by DatasetsRepository::resolve. Keys are display labels, values are arrays of dataset argument values. Duplicate labels are disambiguated with ' #1', ' #2', etc.

```php
[
    'Alice / 42' => ['Alice', 42],
    'Bob / 17'   => ['Bob', 17],
]
```

--------------------------------

### Using expect() function

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Uses the expect() function to create an expectation for a new User instance and asserts it is an instance of User::class.

```php
expect(new User('amanda'))->toBeInstanceOf(User::class);
```

--------------------------------

### Pest\Configuration::use

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Alias of `extend`.

```APIDOC
## `Pest\Configuration::use`

### Description
Alias of `extend`. Binds test-case classes/traits to the current scope.

### Method
`use(string ...$classAndTraits): UsesCall`

### Parameters
- `$classAndTraits` (string) - Required - One or more class or trait names.

### Returns
- `UsesCall` - The uses call object for further configuration.

### Example
```php
pest()->use(TestCase::class);
```
```

--------------------------------

### Pest\Expectations\HigherOrderExpectation

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/opposite-each-higher-order.md

Documentation for the HigherOrderExpectation class, including its constructor, methods, and usage examples.

```APIDOC
## `Pest\Expectations\HigherOrderExpectation`

### Description
A higher-order expectation that wraps the result of a method call or property access on an object, allowing chained assertions while keeping a reference to the original expectation.

### Constructor
- `__construct(Expectation $original, mixed $value)` - Creates a new instance with the original expectation and the wrapped value.

### Methods
- `not(): self` - Toggles negation for the next assertion.
- `expect(mixed $value): Expectation` - Creates a new expectation with the given value.
- `and(mixed $value): Expectation` - Chains another expectation with a new value.
- `scoped(Closure $expectation): self` - Runs a closure against the current sub-expectation, then resets to the original value.
- `json(): self` - Decodes the current value as JSON and returns a new instance for assertions.
- `__call(string $name, array $arguments): self` - If the method is an expectation method, executes it against the wrapped value; otherwise, descends further into the result.
- `__get(string $name): self` - If the property is 'not', toggles negation; otherwise, accesses the property on the current value and returns a new instance.

### Usage Example
```php
expect($order)->total->toBe(99.0);          // property access
expect($order)->getTotal()->toBeGreaterThan(0); // method call
$order->total = 0;
expect($order)->total->not->toBe(0);

expect(json_decode($raw))->json()->toHaveKey('status');
```
```

--------------------------------

### beforeAll() and afterAll() function signatures

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Signatures for the `beforeAll()` and `afterAll()` functions. Register file-scoped hooks executed once before/after all tests in the file. Throws exceptions when called inside a `describe` block or when registered twice.

```php
function beforeAll(Closure $closure): void
function afterAll(Closure $closure): void
```

--------------------------------

### toMatchSnapshot

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Documentation for the toMatchSnapshot expectation matcher, including its signature, parameters, behavior, and usage examples.

```APIDOC
## toMatchSnapshot

### Description
Asserts that the current expectation value matches a stored snapshot. If the snapshot does not exist, it is created automatically (unless in CI without update mode), otherwise the test fails with a message instructing to run Pest with --update-snapshots. When --update-snapshots is active, the snapshot is rewritten if different.

### Method
`toMatchSnapshot`

### Signature
```php
public function toMatchSnapshot(string $message = '', ?string $as = null): self
```

### Parameters
- **$message** (string) - Optional - Custom failure message. Default: `''`.
- **$as** (?string) - Optional - Named snapshot suffix; `null` means next sequential snapshot. Default: `null`.

### Behavior
- Serialization order: string value → `toSnapshot()` → `__toString()` → `toString()` → `TestResponse::getContent()` → `json_encode` (arrays, `Traversable`→`iterator_to_array`, `JsonSerializable`→`jsonSerialize()`) → `toArray()` object → otherwise `InvalidExpectationValue::expected('array|object|string')`.
- Snapshot naming: sequential snapshots per test (`next()`); `$as` selects a named snapshot (`named($as)`, `__{suffix}`).
- Missing snapshot: created automatically if `SnapshotPlugin::shouldCreateMissingSnapshots()` (update mode or not on CI); otherwise fails with `Snapshot is missing at [path]. Run Pest with --update-snapshots to create it.`
- Comparison is done on `Snapshot::normalize` (CRLF→LF) output.

### Example
```php
test('renders the page', function (): string {
    return view('home');
})->visit('https://example.com'); // browser plugin

expect('<h1>Hi</h1>')->toMatchSnapshot();
expect($order)->toMatchSnapshot('order payload');
```
```

--------------------------------

### Instance-style arch expectations

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-arch.md

Shows instance-style arch expectations for classes, usage, implementation, and usage restrictions. Use these to assert architectural rules on namespaces or classes.

```php
expect('App\Models')->classes()->toBeFinal();

expect('App\Services\Accounts')->toUse('App\Support\Money');

expect('App\Models\User')->toImplement(\Stringable::class);

expect('App\Http\*')->toOnlyBeUsedIn('App\Http\Controllers');
```

--------------------------------

### Display Pest version with --version

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/cli-plugins.md

Runs Pest with the --version flag to render the version view (e.g., 'Pest Testing Framework 5.3.0.') and exit with code 0.

```bash
php bin/pest --version
```

--------------------------------

### Pest\Configuration\Project::jira()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Configures Jira URL templates for issues.

```APIDOC
## `Pest\Configuration\Project::jira()`

### Description
Configures the project to use Jira URLs for issues.

### Method
`jira`

### Signature
`public function jira(string $namespace, string $project): self`

### Parameters
- **$namespace** (string) - Required - The Jira namespace (e.g., `acme`).
- **$project** (string) - Required - The Jira project key (e.g., `PAY`).

### Returns
`self` - Returns the same instance for chaining.

### Effect
Sets `issues` to `https://{namespace}.atlassian.net/browse/{project}-%s`.

### Example
```php
pest()->project()->jira('acme', 'PAY');
```
```

--------------------------------

### mutates() usage example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Shows how to use `mutates()` in a test file to declare that the test mutates a specific class.

```php
mutates('App\Services\InvoiceGenerator');

test('generates', function (): void { /* ... */ });
```

--------------------------------

### Configure project URL templates

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Configures the project URL templates using the jira() and custom() methods. The jira() call sets the Jira URL pattern, and custom() sets arbitrary templates with %s placeholders.

```php
pest()->project()->jira('acme', 'PAY');
pest()->project()->custom('https://bugs.acme.test/browse/%s', 'https://pr.acme.test/%s', 'https://people.acme.test/%s');
```

--------------------------------

### Bootable plugin contract

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/contracts.md

Contract for plugins that need to boot after kernel bootstrappers. Executed by CallsBoot::execute.

```php
/**
 * @internal
 */
interface Bootable
{
    public function boot(): void;
}
```

--------------------------------

### Intercepting 'toBe' for strings

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Example of intercepting the 'toBe' expectation for string values, triggering a warning and using toEqual instead.

```php
use function Pest\expect;

expect()->intercept('toBe', 'string', function (string $expected): void {
    trigger_error('Unexpected string equality', E_USER_WARNING);

    $this->and($this->value)->toEqual($expected);
});

expect('a')->toBe('a'); // intercepted for strings only
```

--------------------------------

### Using Pest\version()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Imports and calls Pest\version() to echo the Pest version. Outputs '5.3.0'.

```php
use function Pest\version;

echo version(); // 5.3.0
```

--------------------------------

### beforeAll() / afterAll()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/global-functions.md

Register a file-scoped hook executed once before/after all tests in the file. Throws exceptions when called inside a `describe` block or registered twice in the same file.

```APIDOC
## `beforeAll()` / `afterAll()`

### Description
Register a file-scoped hook executed once before/after all tests in the file. Throws exceptions when called inside a `describe` block or registered twice in the same file.

### Signatures
```php
function beforeAll(Closure $closure): void
function afterAll(Closure $closure): void
```

### Parameters
- **$closure** (Closure) - Required - Hook body, bound to the test-case class.

### Exceptions
- `BeforeAllWithinDescribe` - Thrown when called inside a `describe` block.
- `AfterAllWithinDescribe` - Thrown when called inside a `describe` block.
- `BeforeAllAlreadyExist` - Thrown when registered twice in the same file.
- `AfterAllAlreadyExist` - Thrown when registered twice in the same file.

### Example
```php
beforeAll(function () {
    database()->migrate();
});

afterAll(function () {
    database()->drop();
});
```

```

--------------------------------

### toHaveSnakeCaseKeys example

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Recursively applies toBeSnakeCase to string keys of nested iterables. Throws InvalidExpectationValue::expected('iterable') if the value is not iterable.

```php
expect(['user_name' => ['id' => 1]])->toHaveSnakeCaseKeys();
```

--------------------------------

### Pest\Configuration::__call

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Delegates to `$this->uses()->$name(...)`.

```APIDOC
## `Pest\Configuration::__call`

### Description
Delegates to `$this->uses()->$name(...)`.

### Method
`__call(string $name, array $arguments): mixed`

### Parameters
- `$name` (string) - Required - The method name to delegate.
- `$arguments` (array) - Required - The arguments to pass.

### Returns
- `mixed` - The result of the delegated call.

### Example
```php
pest()->someMethod();
```
```

--------------------------------

### DescribeCall constructor

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/describe-and-hooks.md

Constructor signature for DescribeCall, showing the required parameters: test suite, filename, description, and tests closure.

```php
public function __construct(
    public readonly TestSuite $testSuite,
    public readonly string $filename,
    public readonly Description $description,
    public readonly Closure $tests
)
```

--------------------------------

### Pest\Configuration\Printer::compact()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Enables the compact result printer for Pest output.

```APIDOC
## `Pest\Configuration\Printer::compact()`

### Description
Enables the compact result printer for Pest output.

### Method
`compact`

### Signature
`public function compact(): self`

### Parameters
None.

### Returns
`self` - Returns the same instance for chaining.

### Example
```php
$printer->compact();
```
```

--------------------------------

### Catching Throwable with Panic::with

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/runtime-kernel.md

Internal usage example showing how Panic::with is called from the test lifecycle to handle any throwable, as seen in src/Concerns/Testable.php:154.

```php
// internal usage from test lifecycle:
catch (Throwable $e) { Panic::with($e); }   // src/Concerns/Testable.php:154
```

--------------------------------

### Configure Tia default branch and baseline

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Configures the Tia plugin to use 'main' as the default branch and fetch the CI baseline graph. Available only when pest-plugin-tia is enabled via the Bootstrapper.

```php
pest()->tia()->defaultBranch('main')->baselined();
```

--------------------------------

### Pest\Configuration::project

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Returns a `Configuration\Project` instance for issue/PR/assignee URL providers.

```APIDOC
## `Pest\Configuration::project`

### Description
Returns a `Configuration\Project` instance for issue/PR/assignee URL providers.

### Method
`project(): Configuration\Project`

### Returns
- `Configuration\Project` - The project configuration object.

### Example
```php
pest()->project()->github('acme/app');
```
```

--------------------------------

### Pest Expectation Conditional Methods

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation.md

Documentation for the `match()`, `when()`, and `unless()` methods on the Pest expectation object, including signatures, parameters, return types, and usage examples.

```APIDOC
## `match()`

### Description
Pattern-matches a subject value or closure against a set of expressions. The matched entry whose key is loosely equal to the subject runs: a callable receives a new expectation wrapping the current value, while a literal value is asserted with `toEqual`. Throws `PHPUnit\Framework\ExpectationFailedException` with message `Unhandled match value.` when no key matches.

### Method
`match`

### Signature
```php
public function match(mixed $subject, array $expressions): self
```

### Parameters
- **$subject** (mixed) - Required - The value or 0-arg closure to match against the keys of `$expressions`.
- **$expressions** (array) - Required - Associative array mapping keys to either a callable receiving `self<TValue>` or a literal value to assert with `toEqual`.

### Return Value
`self<TValue>` - The current expectation instance.

### Throws
`PHPUnit\Framework\ExpectationFailedException` - When no key in `$expressions` matches `$subject`.

### Example
```php
expect(42)->match('status', [
    'ok' => fn (Expectation $v): void => $v->toBe(200),
    'error' => fn (Expectation $v): void => $v->toBe(500),
]);
```
```

```APIDOC
## `when()` / `unless()`

### Description
Conditionally run a callback on the current expectation. `when` executes the callback when the condition is truthy, while `unless` executes it when the condition is falsy. Both methods return the current expectation instance for chaining.

### Method
`when` / `unless`

### Signatures
```php
public function when(callable|bool $condition, callable $callback): self
public function unless(callable|bool $condition, callable $callback): Expectation
```

### Parameters
- **$condition** (callable|bool) - Required - A boolean value or a 0-arg closure returning a boolean.
- **$callback** (callable) - Required - A callable receiving `self<TValue>` (for `when`) or `Expectation<TValue>` (for `unless`) and returning mixed.

### Return Value
- `when`: `self<TValue>` - The current expectation instance.
- `unless`: `Expectation<TValue>` - The current expectation instance.

### Example
```php
expect($tax)->when($region === 'EU', fn (Expectation $v): void => $v->toBeGreaterThan(0));
```
```

--------------------------------

### Using equality and identity matchers (toBe, toEqual, toEqualWithDelta, toBeNull)

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Shows usage of the equality and identity matchers: toBe for identical values, toEqual for deep equality, toEqualWithDelta for approximate equality, and toBeNull for null checks. Each matcher returns the same expectation and accepts an optional custom failure message.

```php
expect($a)->toBe($a);                       // same instance
expect([1, 2])->toEqual([1, 2]);            // deep equality
expect(10.0)->toEqualWithDelta(10.1, 0.2);  // within delta
expect($maybe)->toBeNull();
```

--------------------------------

### Boolean and truthiness matchers usage

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/expectation-matchers.md

Example of using toBeTrue and toBeFalsy matchers. toBeTrue asserts the value is true, toBeFalsy asserts the value is false when cast to boolean.

```php
expect($flag)->toBeTrue();
expect(0)->toBeFalsy();
```

--------------------------------

### wip(array|string|null $note = null, array|string|null $assignee = null, array|string|int|null $issue = null, array|string|int|null $pr = null): self

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/test-call.md

Marks a test as work-in-progress by attaching metadata, without skipping the test.

```APIDOC
## wip(array|string|null $note = null, array|string|null $assignee = null, array|string|int|null $issue = null, array|string|int|null $pr = null): self

### Description
Applies metadata to mark a test as work-in-progress. Does not skip the test. Accepts arrays for multiple values.

### Method
wip

### Parameters
- **$note** (array|string|null) - Optional - Note or notes for the WIP.
- **$assignee** (array|string|null) - Optional - Assignee or assignees.
- **$issue** (array|string|int|null) - Optional - Issue reference(s).
- **$pr** (array|string|int|null) - Optional - Pull request reference(s).

### Example
```php
test('actual feature', function (): void {
    // ...
})->wip(issue: 123, pr: 456);
```
```

--------------------------------

### describe() usage with nesting

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/describe-and-hooks.md

Example of using describe() to group tests and nest describe blocks. The final description for the nested test is "A B nested".

```php
describe('Shopping cart', function () {
    test('adds an item', function (): void {
        // ...
    });
});

describe('A', function () {
    describe('B', function () {
        test('nested', function (): void {
            // final description: "A B nested"
        });
    });
});
```

--------------------------------

### Pest\Configuration\Project::github()

Source: https://github.com/pestphp/pest/blob/5.x/_autodocs/api-reference/configuration.md

Configures GitHub URL templates for issues, pull requests, and assignees.

```APIDOC
## `Pest\Configuration\Project::github()`

### Description
Configures the project to use GitHub URLs for issues, pull requests, and assignees.

### Method
`github`

### Signature
`public function github(string $project): self`

### Parameters
- **$project** (string) - Required - The GitHub project identifier (e.g., `owner/repo`).

### Returns
`self` - Returns the same instance for chaining.

### Effect
Sets `issues` to `https://github.com/{project}/issues/%s`, `prs` to `https://github.com/{project}/pull/%s`, and `assignees` to `https://github.com/%s`.
```
Tokens:
Raw