PestStan

https://github.com/mrpunyapal/peststan
Admin
PestStan is a PHPStan extension for Pest PHP testing framework that provides type-safe expectations,...
Tokens:24,262
Snippets:397
Trust Score:9.4
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Full Configuration Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

A comprehensive example showing includes, parameters, and error suppression.

```neon
includes:
    - vendor/mrpunyapal/peststan/extension.neon

parameters:
    level: max
    paths:
        - app
        - tests
    
    peststan:
        testCaseClass: Tests\TestCase
        pestConfigFiles: []
    
    ignoreErrors:
        - identifier: pest.expectation.redundant
          path: tests/Feature/LegacyTest.php
```

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

### Install Project Dependencies

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Run this command to install all necessary project dependencies using Composer.

```bash
composer install
```

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

### Property Chain Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Demonstrates the basic usage of the each() method in an expectation chain.

```php
expect(['a', 'b'])->each()
// Type: HigherOrderExpectation<array{string, string}, string>
```

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

### Return type resolution examples

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-function-return-type-extension.md

Examples showing the expected return types for various Pest function calls.

```php
// For: expect('hello')
// Returns: Expectation<string>

// For: expect(42)
// Returns: Expectation<int>

// For: expect(['a' => 1])
// Returns: Expectation<array{a: int}>

// For: it('test', function() { })
// Returns: TestCall

// For: beforeAll(function() { })
// Returns: null
```

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

### Example directoryMap data

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Shows the expected format for the directory map array.

```php
[
    '/app/tests/Feature/' => ['Tests\TestCase'],
    '/app/tests/Unit/' => ['Tests\TestCase', 'Tests\UnitTrait'],
]
```

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

### Resolve Property Fetch Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Demonstrates the return types for property access on expectations.

```php
// expect('hello')->not
// Returns: OppositeExpectation<string>

// expect([1, 2])->each
// Returns: HigherOrderExpectation<array{int, int}, int>
```

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

### Integrate with PHPStan

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Example of initializing the discoverer using paths and root directory provided by PHPStan.

```php
// Injected by PHPStan
$discoverer = new PestFileDiscoverer(
    scanPaths: %paths%,  // From phpstan.neon
    rootDir: %currentWorkingDirectory%,
);

$pestFiles = $discoverer->discoverPestFiles(
    extraFiles: %peststan.pestConfigFiles%
);
```

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

### Example usage of resolveBindings

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Demonstrates how resolveBindings returns applicable class or trait bindings based on the file directory.

```php
// tests/Pest.php:
// uses(Tests\TestCase::class)->in('Feature');

$bindings = $reader->resolveBindings('/app/tests/Feature/UserTest.php');
// Returns: ['Tests\TestCase']

$bindings = $reader->resolveBindings('/app/tests/Unit/ModelTest.php');
// Returns: [] (no binding for Unit directory)
```

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

### Install PestStan

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Install the PestStan package using Composer. This command adds the package as a development dependency.

```bash
composer require --dev mrpunyapal/peststan
```

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

### Resolve Higher-Order And Call Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Shows the behavior of the and() method when breaking out of higher-order mode.

```php
// expect($items)->each()->and(42)
// Returns: Expectation<int>
```

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

### PestHookPropertyReader Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Demonstrates the mapping of property names to RHS expressions extracted from beforeEach hooks.

```php
// In test file:
beforeEach(function () {
    $this->user = new User();
    $this->name = 'John';
    $this->count = 42;
});

// Returns:
[
    'user' => [New_(User::class)],
    'name' => [String_('John')],
    'count' => [LNumber(42)],
]
```

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

### Example usage of isFunctionSupported

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Demonstrates which functions return true or false when evaluated by the extension.

```php
// Returns true for:
it('test', function() { ... })
describe('suite', function() { ... })
beforeEach(function() { ... })

// Returns false for:
array_map(function() { ... })
usort($array, function() { ... })
```

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

### Resolve Method Call Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Demonstrates return types for method calls on HigherOrderExpectation instances.

```php
// expect($items)->each()->toBeInt()
// Returns: HigherOrderExpectation<array, int>

// expect($items)->each()->and($newValue)
// Returns: Expectation<newValueType>
```

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

### Create root ExpectationChainState

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/types.md

Static factory method to initialize the start of an expectation chain.

```php
public static function root(Type $valueType): self
```

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

### Usage of isFunctionSupported

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-function-return-type-extension.md

Example demonstrating how to check if a function is supported before resolving its type.

```php
if ($extension->isFunctionSupported($reflection)) {
    $type = $extension->getTypeFromFunctionCall($reflection, $functionCall, $scope);
}
```

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

### Resolve Higher-Order Property Fetch Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Illustrates property access on an already-accessed HigherOrderExpectation.

```php
// expect($items)->each()->name
// 1. expect($items) returns Expectation<array>
// 2. ->each returns HigherOrderExpectation<array, itemType>
// 3. ->name returns HigherOrderExpectation<array, stringType>
```

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

### Resolve Expectation Property Fetch Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Shows how dynamic property access is handled for higher-order matchers.

```php
// expect($user)->toHaveProperty('name')
// For: expect($user)->name
// Looks up the 'name' property on $user
// Returns: HigherOrderExpectation<$user, string>
```

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

### Architecture Testing Support Examples

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Demonstrates PestStan's full support for architecture testing methods, including extending, ignoring, and class-level assertions.

```php
expect('App\Models')
    ->toExtend('Illuminate\Database\Eloquent\Model')
    ->ignoring('App\Models\Legacy');

expect('App')
    ->classes()
    ->toBeFinal();

expect('App\Actions')->toBeInvokable();
expect('App\DTOs')->toBeReadonly();
expect('App')->toUseStrictTypes();
```

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

### TestCall Fluent Chaining Example

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Illustrates the proper typing for fluent chaining of `TestCall` methods in Pest.

```php
it('does something', function () { /* ... */ })
    ->with(['a', 'b'])
    ->group('unit', 'feature')
    ->skip(false)
    ->depends('other test')
    ->throws(RuntimeException::class)
    ->repeat(3);
```

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

### Property Type Inference Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Example of property assignment in a Pest test that triggers the inference flow.

```php
beforeEach(function () {
    $this->user = User::factory()->create();
    $this->count = 42;
});

it('test', function () {
    $this->user->name;
    strlen($this->count);
});
```

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

### TestCaseDynamicPropertyTypeExtension Usage

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Example of property assignment within a beforeEach hook that the extension resolves.

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

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

### Example usage of resolveGlobalUses

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Demonstrates how resolveGlobalUses filters out extend/extends declarations and returns only uses() bindings.

```php
// tests/Pest.php:
// uses(Trait1::class)->in('Feature');
// pest()->extend(BaseTrait::class)->in('Feature');

$uses = $reader->resolveGlobalUses('/app/tests/Feature/Test.php');
// Returns: [
//   ['class' => 'Trait1', 'config' => '/app/tests/Pest.php'],
// ]
// (BaseTrait is not included)
```

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

### Example of type preservation in negation chains

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/opposite-expectation-method-return-type-extension.md

Demonstrates how the extension maintains the generic type parameter through negated expectation calls.

```php
// expect('hello')->not()->toBeInt()
// 1. expect('hello') → Expectation<string>
// 2. ->not() → OppositeExpectation<string>
// 3. ->toBeInt() → Expectation<string> (thanks to this extension)
//    Without this: would be Mixins
Expectation<mixed>

// expect(42)->not()->toBeString()
// 1. expect(42) → Expectation<int>
// 2. ->not() → OppositeExpectation<int>
// 3. ->toBeString() → Expectation<int>
//    Without this: would be Mixins
Expectation<mixed>
```

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

### Example usage of getClosureThisTypeFromFunctionCall

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Shows how the extension resolves the $this type based on Pest configuration bindings.

```php
// Pest.php:
// uses(Tests\TestCase::class)->in('Feature');

// tests/Feature/ExampleTest.php:
it('can use test case', function () {
    // $this is Tests\TestCase
    $this->get('/');
});
```

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

### Manual Extension Registration

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

Include the extension manually in phpstan.neon if not using the automatic installer.

```neon
includes:
    - vendor/mrpunyapal/peststan/extension.neon
```

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

### Expectation type narrowing examples

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-method-return-type-extension.md

Illustrates how assertion methods narrow the generic type of an Expectation instance.

```php
// expect('hello')->toBeString()
// Input: Expectation<string|int>
// Asserted type: string
// Output: Expectation<string>

// expect(42)->toBeInstanceOf(User::class)
// Input: Expectation<int|User>
// Asserted type: User
// Output: Expectation<User>

// expect('test')->and(42)
// Input: Expectation<string>
// Asserted type: null (and() is a passthrough)
// Output: Expectation<int> (new value type)
```

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

### Incorrect Usage of $this in beforeAll()

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

The `beforeAll()` hook runs in a static context, meaning `$this` is not available. Use `beforeEach()` if you need access to `$this` for setup.

```php
beforeAll(function () {
    $this->db = new Database; // ✘ beforeAll() runs in static context — $this is not available. Use beforeEach() instead.
});
```

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

### Redundant Expectation Suppression Example

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-semantic-analyzer.md

Demonstrates how subsequent identical assertions on a narrowed type are suppressed to reduce noise.

```php
expect(42 | 'hello')
    ->toBeInt()     // Asserts type narrowing to int
    ->toBeInt();    // Redundant, but suppressed
```

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

### Example of type preservation without narrowing

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/opposite-expectation-method-return-type-extension.md

Shows that opposite expectations preserve the original type rather than narrowing it.

```php
// expect(42 | 'hello')->not()->toBeInt()
// Should NOT narrow the type.
// The expression still wraps (42 | 'hello'), just with negated assertions.
// Returns: Expectation<42|'hello'>
```

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

### Pest.php Configuration for $this Binding

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Example of configuring Pest.php to use a specific TestCase class for tests within a directory, ensuring proper $this binding in test closures.

```php
// tests/Pest.php
uses(Tests\TestCase::class)->in('Feature');

// tests/Feature/ExampleTest.php
it('can access test case methods', function () {
    $this->get('/');  // PHPStan knows $this is Tests\TestCase
});

beforeEach(function () {
    $this->assertTrue(true);   // Works in hooks too
});
```

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

### Type Hinting for Factory Calls with Dynamic Properties

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Demonstrates how to use @var annotation for method-call chains like factory calls when setting dynamic properties on $this to guide type inference.

```php
beforeEach(function () {
    /** @var User $user */
    $user        = User::factory()->create();
    $this->user  = $user;
});
```

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

### Pest Global Helper Return Types

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Example of how Pest global helper functions like expect(), pest(), uses(), it(), test(), todo(), describe(), and fixture() have their return types overridden.

```php
expect($value) → Expectation<typeof $value>
pest() → Configuration
uses(...) → UsesCall
it() / test() / todo() → TestCall
describe() → DescribeCall
beforeEach() / afterEach() → pending call wrappers
fixture() → string when the installed Pest version provides the helper
beforeAll() / afterAll() / dataset() / covers() / mutates() → null
```

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

### Pest Function Return Types

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Provides accurate return types for Pest's core global functions and newer helpers based on the installed Pest version.

```php
expect($value) // Expectation<TValue>
pest() // Configuration
uses(...) // UsesCall
it() / test() / todo() // TestCall
describe() // DescribeCall
beforeEach() // BeforeEachCall
afterEach() // AfterEachCall
fixture() // string when available
beforeAll() / afterAll() // null
dataset() / covers() / mutates() // null
```

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

### Get closure argument index

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-function-detector.md

Use getClosureArgIndex to determine the argument position of the closure for a given Pest function.

```php
$index = PestFunctionDetector::getClosureArgIndex('it');
// Returns 1 because it(description, closure)

$hookIndex = PestFunctionDetector::getClosureArgIndex('beforeEach');
// Returns 0 because beforeEach(closure)
```

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

### Initialize PestConfigReader

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Constructor for the PestConfigReader class, requiring an array of configuration file paths and a file discoverer service.

```php
public function __construct(
    private readonly array $pestConfigFiles,
    private readonly PestFileDiscoverer $fileDiscoverer,
)
```

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

### Define the TestClosureThisTypeExtension constructor

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Initializes the extension with a configuration reader and an optional fallback TestCase class.

```php
public function __construct(
    private readonly PestConfigReader $pestConfigReader,
    private readonly string $testCaseClass = TestCase::class,
)
```

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

### Configure pestConfigFiles

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

Explicitly defines paths to Pest.php files if auto-discovery fails or is unreliable.

```neon
parameters:
    peststan:
        pestConfigFiles:
            - tests/Pest.php
            - tests/Bootstrap/Pest.php
```

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

### Register Extension Automatically

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/README.md

Use extension-installer to automatically register the extension.

```bash
composer require --dev phpstan/extension-installer
```

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

### Run Static Analysis with PHPStan

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Execute this command to perform static analysis on the project using PHPStan.

```bash
composer test:types
```

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

### Configure Analysis Paths

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

Define directories for PHPStan to search for Pest.php files.

```neon
parameters:
    paths:
        - app
        - tests
        - src
```

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

### Parsing Pest.php Configuration

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Illustrates the use of nikic/php-parser with NameResolver for parsing Pest.php configuration files and resolving class names.

```php
Parses Pest.php configuration files using nikic/php-parser with NameResolver to resolve fully-qualified class names from use statements. Discovers Pest.php files automatically from PHPStan's analysis paths, or from explicit peststan.pestConfigFiles.
```

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

### Run All Project Checks

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Execute this command to run all automated checks, including code quality, style, static analysis, and unit tests.

```bash
composer test
```

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

### Perform standalone file parsing

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Demonstrates parsing a specific Pest.php file and using NodeFinder to locate function calls within the AST.

```php
[$stmts, $aliases] = $discoverer->parseFile('/app/tests/Pest.php') ?? [[], []];

// Analyze the AST
$nodeFinder = new NodeFinder();
$calls = $nodeFinder->findInstanceOf($stmts, FuncCall::class);
```

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

### Run Unit Tests with Pest

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Use this command to run the unit tests for the project using the Pest testing framework.

```bash
composer test:unit
```

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

### Initialize PestFileDiscoverer

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Constructor for the service, typically injected by PHPStan using project paths and the working directory.

```php
public function __construct(
    private readonly array $scanPaths,
    private readonly string $rootDir = '',
)
```

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

### Construct the ExpectationMethodReturnTypeExtension

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-method-return-type-extension.md

Initializes the extension with optional registry and type narrower dependencies.

```php
public function __construct(
    ?ExpectationMatcherRegistry $matcherRegistry = null,
    ?ExpectationTypeNarrower $typeNarrower = null,
)
```

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

### Project Structure Overview

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

This outlines the directory and file structure of the PestStan project, highlighting key components and their purposes.

```text
PestStan/
├── src/Type/Pest/
│   ├── PestFunctionReturnTypeExtension.php            # Pest global helper return types
│   ├── ExpectationMethodReturnTypeExtension.php       # Type narrowing for assertion methods
│   ├── OppositeExpectationMethodReturnTypeExtension.php # not() return types
│   ├── TestClosureThisTypeExtension.php               # $this binding in closures
│   ├── PestConfigReader.php                           # Pest.php auto-detection for TestCase
│   ├── TestCallMethodsClassReflectionExtension.php    # TestCall fluent methods from Pest mixins and custom testCaseClass
│   ├── TestCasePropertiesExtension.php                # Dynamic property support
│   └── PestTestCaseProperty.php                       # PropertyReflection for dynamic props
├── tests/
│   ├── Pest.php                                       # Pest bootstrap
│   ├── TestCase.php                                   # Base test case
│   ├── CustomTestCaseTestCase.php                     # Test case for custom TestCase config
│   ├── extension.neon                                 # Test PHPStan config
│   └── Type/
│       ├── ExpectTypeTest.php                         # Main test runner
│       ├── CustomTestCaseTest.php                     # Custom TestCase test runner
│       ├── Fixtures/
│       │   └── CustomTestCase.php                     # Custom test case fixture for $this and TestCall method coverage
│       ├── custom-testcase-extension.neon             # PHPStan config for custom TestCase tests
│       └── data/
│           ├── expect-function.php                    # expect() return type tests
│           ├── expectation-methods.php                # Assertion method type tests
│           ├── test-closures.php                      # $this binding + dynamic property tests
│           ├── test-closures-custom-testcase.php      # Custom TestCase $this binding tests
│           ├── test-call-methods.php                  # TestCall chaining tests
│           ├── pest-functions.php                     # Pest global helper return type tests
│           └── arch-expectations.php                  # Architecture testing type tests
├── extension.neon                                     # PHPStan extension config
├── composer.json
├── phpstan.neon.dist
├── phpunit.xml.dist
├── pint.json
└── rector.php
```

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

### Registering the Matcher Registry in extension.neon

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-matcher-registry.md

The registry is designed for constructor injection and does not require explicit service tagging in the configuration.

```neon
# Implicitly available for constructor injection
# No explicit registration needed; created on demand
```

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

### Define Pest.php bindings

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

The extension automatically discovers uses() and pest()->use() declarations from Pest.php files.

```php
// tests/Pest.php
uses(Tests\TestCase::class)->in('Feature', 'Unit');

// tests/Integration/Pest.php
pest()->use(IntegrationTestCase::class)->in('Integration');
```

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

### Initialize ExpectationSemanticAnalyzer

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-semantic-analyzer.md

Constructor for the analyzer, optionally accepting an ExpectationChainStateResolver instance.

```php
public function __construct(?ExpectationChainStateResolver $chainStateResolver = null)
```

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

### Usage of TestCall fluent API methods

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Demonstrates how public helper methods from a TestCase class become available on the TestCall fluent API.

```php
it('test', function () { })
    ->with(['a', 'b'])
    ->group('unit')
    ->publicHelper()  // from your TestCase
    ->skip(false);
```

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

### Consume Pest Diagnostics

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/overview.md

Demonstrates how to generate and access properties of an immutable Pest diagnostic object.

```php
$diagnostic = PestDiagnostics::impossibleExpectation('toBeString', 'int');

$diagnostic->toArray();  // JSON-serializable array
$diagnostic->identifier;  // Canonical identifier
$diagnostic->severity;    // 'error' or 'warning'
```

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

### Empty describe() Block

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

A `describe()` block that contains no `it()` or `test()` calls is likely a mistake and will be flagged. Ensure it includes at least one test.

```php
describe('UserService', function () {
    beforeEach(fn () => null);
    // ✘ describe() block 'UserService' contains no tests.
});
```

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

### Define findPestFilesInDirectory method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Recursively searches a directory for Pest.php files up to a maximum depth of 20.

```php
private function findPestFilesInDirectory(string $dir, array &$files): void
```

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

### Configure PestStan in phpstan.neon

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/overview.md

Define the test case class and configuration files within the PHPStan configuration file.

```neon
parameters:
    peststan:
        testCaseClass: App\Testing\TestCase
        pestConfigFiles: []
```

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

### Run PestStan test suite

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/overview.md

Execute various test commands using Composer to verify code style, types, and unit tests.

```bash
composer test          # All checks
composer test:lint     # Code style
composer test:types    # Type checking
composer test:unit     # Unit tests
```

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

### Register Extension in Neon

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Configuration required to register the extension in the extension.neon file.

```neon
services:
    -
        class: PestStan\Type\Pest\HigherOrderExpectationTypeExtension
        tags:
            - phpstan.broker.expressionTypeResolverExtension
```

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

### Configure Test Case Binding

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/INDEX.md

Defines the base TestCase class for a specific directory, which is then processed by the configuration reader.

```php
uses(Tests\TestCase::class)->in('Feature');
```

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

### Detect empty describe blocks

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/static-analysis-rules.md

Flags describe blocks that lack any test or it definitions.

```php
describe('UserService', function () {
    beforeEach(fn () => null);
    // ✘ describe() block 'UserService' contains no tests.
});
```

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

### Run All Checks

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Executes all project checks including linting, type analysis, and unit tests. This is the primary command for ensuring code quality.

```bash
composer test        # Run all checks (lint + types + unit)
```

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

### Initialize ExpectationMatcherRegistry

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-matcher-registry.md

Constructor for the registry, allowing optional injection of sub-registries.

```php
public function __construct(
    ?MatcherRequirementRegistry $requirementRegistry = null,
    ?MatcherAssertionRegistry $assertionRegistry = null,
    ?MatcherCategoryRegistry $categoryRegistry = null,
)
```

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

### Define createParser method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Creates a PHP parser instance configured for the newest supported PHP version.

```php
private function createParser(): Parser
```

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

### Dynamic Property Access

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Shows how the extension resolves types through a chain of property access and assertion methods.

```php
expect($users)->each()->name->toEndWith('Smith')
// expect($users) → Expectation<User[]>
// ->each() → HigherOrderExpectation<User[], User>
// ->name → HigherOrderExpectation<User[], string>
// ->toEndWith(...) → HigherOrderExpectation<User[], string>
```

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

### Constructor for HigherOrderExpectationTypeExtension

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Initializes the extension with the required PHPStan reflection provider.

```php
public function __construct(
    private readonly ReflectionProvider $reflectionProvider,
)
```

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

### Registering PestStan Extensions

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Register these services in your extension.neon file to enable PestStan functionality.

```neon
services:
    -
        class: PestStan\Type\Pest\TestCasePropertiesExtension
        tags:
            - phpstan.broker.propertiesClassReflectionExtension

    -
        class: PestStan\Type\Pest\ExpectationPropertiesExtension
        tags:
            - phpstan.broker.propertiesClassReflectionExtension

    -
        class: PestStan\Type\Pest\TestCaseDynamicPropertyTypeExtension
        tags:
            - phpstan.broker.expressionTypeResolverExtension

    -
        class: PestStan\Type\Pest\PestHookPropertyReader

    -
        class: PestStan\Type\Pest\PestInternalClassAccessIgnoreExtension
        tags:
            - phpstan.ignoreErrorExtension

    -
        class: PestStan\Type\Pest\TestCallMethodsClassReflectionExtension
        arguments:
            testCaseClass: %peststan.testCaseClass%
        tags:
            - phpstan.broker.methodsClassReflectionExtension

    -
        class: PestStan\Type\Pest\ProtectedMethodCallIgnoreExtension
        arguments:
            testCaseClass: %peststan.testCaseClass%
        tags:
            - phpstan.ignoreErrorExtension
```

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

### Register the extension in extension.neon

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/opposite-expectation-method-return-type-extension.md

Configuration required to register the extension with PHPStan.

```neon
services:
    -
        class: PestStan\Type\Pest\OppositeExpectationMethodReturnTypeExtension
        tags:
            - phpstan.broker.dynamicMethodReturnTypeExtension
```

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

### Define findPestFilesInAncestors method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Searches ancestor directories upward for Pest.php files until the filesystem root is reached.

```php
private function findPestFilesInAncestors(string $dir, array &$files): void
```

```php
// Given: /app/tests/Feature/Test.php
// Searches: /app/tests/Feature, /app/tests, /app, /
// Finds: /app/tests/Pest.php, /app/Pest.php
```

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

### Register TestClosureThisTypeExtension in extension.neon

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Add the extension service definition to your extension.neon file to enable the custom PHPStan type extension.

```neon
services:
    -
        class: PestStan\Type\Pest\TestClosureThisTypeExtension
        arguments:
            testCaseClass: %peststan.testCaseClass%
        tags:
            - phpstan.functionParameterClosureThisExtension
```

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

### Implement getClass method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/opposite-expectation-method-return-type-extension.md

Returns the class handled by the extension, which is always Pest\Expectations\OppositeExpectation.

```php
public function getClass(): string
```

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

### Resolve bindings for a file

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Method signature for resolving class and trait bindings for a specific test file path.

```php
public function resolveBindings(string $filePath): array
```

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

### Register the Expectation Method Return Type Extension

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-method-return-type-extension.md

Add the extension to your PHPStan configuration file to enable dynamic method return type analysis for Pest expectations.

```neon
services:
    -
        class: PestStan\Type\Pest\ExpectationMethodReturnTypeExtension
        tags:
            - phpstan.broker.dynamicMethodReturnTypeExtension
```

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

### Discover Pest.php files

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Method to locate Pest.php files by scanning configured paths and ancestor directories.

```php
public function discoverPestFiles(array $extraFiles = []): array
```

```php
$discoverer = new PestFileDiscoverer(
    scanPaths: ['/app/tests', '/app/src'],
    rootDir: '/app'
);

$files = $discoverer->discoverPestFiles(['/app/config/Pest.php']);
// Returns: [
//   '/app/config/Pest.php',
//   '/app/tests/Pest.php',
//   '/app/Pest.php',  // from ancestor scan
// ]
```

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

### Parse PHP files into AST

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Parses a file into an AST with name resolution, returning null if parsing fails.

```php
public function parseFile(string $filePath): array{Node[], array<string, string>}|null
```

```php
[$stmts, $useAliases] = $discoverer->parseFile('/app/tests/Pest.php') ?? [[], []];

foreach ($stmts as $stmt) {
    // $stmt is a fully resolved AST node
}
```

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

### Advance ExpectationChainState

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/types.md

Instance method to create a new state for the next step in the chain.

```php
public function next(ExpectationAssertionResult $stepResult): self
```

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

### not() and each() Return Types

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Demonstrates the return types for the `not()` and `each()` expectation methods in Pest.

```php
expect('hello')->not();    // OppositeExpectation<string>
expect([1, 2])->each();    // EachExpectation<array{int, int}>
```

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

### Define parsePestFile method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Parses a single Pest.php file to extract bindings by generating an AST and processing use and pest method chains.

```php
private function parsePestFile(string $filePath): void
```

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

### Run Pest Unit Tests

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Executes the unit tests written using the Pest PHP testing framework. This command verifies the correctness of individual components of the project.

```bash
composer test:unit   # Run Pest unit tests
```

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

### Use Higher-Order Expectations

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/README.md

Static analysis support for higher-order expectations on collections.

```php
expect($users)->each()
    ->toBeInstanceOf(User::class)
    ->toHaveProperty('email');
```

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

### Handle unset properties

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Properties not set in beforeEach remain mixed, requiring @var annotations for type narrowing.

```php
// Property $user is never set in beforeEach
// so $this->user inside it() is mixed

it('test', function () {
    // PHPStan treats this as mixed
    $this->user->name;  // Error: Cannot access property on mixed
});
```

```php
beforeEach(function () {
    /** @var User $user */
    $user = User::factory()->create();
    $this->user = $user;
});
```

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

### Define extractInDirectories method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Extracts directory strings from in() method arguments, returning null if paths are dynamic.

```php
private function extractInDirectories(MethodCall $methodCall): ?array
```

```php
// ->in('Feature', 'Unit')
// Returns: ['Feature', 'Unit']

// ->in($dynamicPath)
// Returns: null (static analysis cannot prove coverage)
```

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

### Resolve global uses

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Method signature for retrieving global uses() declarations, excluding extend/extends configurations.

```php
public function resolveGlobalUses(string $filePath): array
```

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

### Custom Helper Method Chaining

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Shows how PestStan exposes public helper methods from a custom TestCase class on `TestCall` chains.

```php
it('uses a custom helper')->publicHelper();
```

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

### Define Matcher Requirements

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-matcher-registry.md

Constants defining the pre-conditions required by matchers.

```php
public const REQUIREMENT_STRING = 'string'
public const REQUIREMENT_ITERABLE = 'iterable'
public const REQUIREMENT_COUNTABLE_OR_ITERABLE = 'countable_or_iterable'
```

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

### Automatic TestCase Detection via uses() Pattern

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

PestStan automatically detects the TestCase class used in test directories by reading Pest.php files and supporting the uses() pattern.

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

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

### Prevent beforeAll and afterAll in describe blocks

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/static-analysis-rules.md

Lifecycle hooks like beforeAll and afterAll are not supported inside describe blocks and will throw errors at runtime.

```php
describe('suite', function () {
    beforeAll(function () { });  // ✘ beforeAll() cannot be used inside describe() blocks.
    afterAll(function () { });   // ✘ afterAll() cannot be used inside describe() blocks.
});
```

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

### Define globalUseDirectoryMap structure

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Defines the internal array structure for mapping directory paths to use-only bindings.

```php
/** @var array<string, list<array{class: string, config: string}>> */
private array $globalUseDirectoryMap = [];
```

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

### Define resolvePestClassNames method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Recursively walks a pest() chain to categorize extend and use bindings.

```php
private function resolvePestClassNames(Expr $expr): ?array
```

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

### Define PestStan Parameters

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

The base structure for configuring PestStan within the parameters section of phpstan.neon.

```neon
parameters:
    peststan:
        testCaseClass: string
        pestConfigFiles: list<string>
```

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

### Define resolveUsesClassNames method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Recursively walks a uses() chain to extract all class arguments.

```php
private function resolveUsesClassNames(Expr $expr): array
```

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

### Apply Code Fixes with Rector and Pint

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Use this command to automatically apply code style and quality fixes using Rector and Pint.

```bash
composer lint
```

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

### Configure testCaseClass

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

Sets the fallback class for $this in test closures when no bindings are found in Pest.php.

```neon
parameters:
    peststan:
        testCaseClass: App\Testing\TestCase
```

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

### Run PHPStan Analysis

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Executes PHPStan, a static analysis tool, to check for type errors and other code quality issues. This command helps in identifying potential bugs early.

```bash
composer test:types  # Run PHPStan analysis
```

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

### Define directoryMap structure

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Defines the internal array structure for mapping normalized directory paths to class or trait names.

```php
/** @var array<string, list<string>> Maps normalized directory paths to class/trait names */
private array $directoryMap = [];
```

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

### Check function support

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-function-return-type-extension.md

Signature for the isFunctionSupported method used to determine if the extension handles a specific function.

```php
public function isFunctionSupported(FunctionReflection $functionReflection): bool
```

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

### Set Analysis Level

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

Configure the PHPStan analysis level.

```neon
parameters:
    level: max
```

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

### Lifecycle Hooks Inside describe() Detection

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Rules `pest.lifecycle.beforeAllDisallowed` and `pest.lifecycle.afterAllDisallowed` detect disallowed `beforeAll()` or `afterAll()` calls within `describe()` blocks, which cause runtime errors.

```php
describe('suite', function () {
    beforeAll(function () { /* ... */ });
    // ✘ beforeAll() cannot be used inside describe() blocks.

    afterAll(function () { /* ... */ });
    // ✘ afterAll() cannot be used inside describe() blocks.
});
```

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

### Define extractPestBindings method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Extracts bindings from the Pest fluent API, including extend, extends, use, and uses method chains.

```php
private function extractPestBindings(
    NodeFinder $nodeFinder,
    array $stmts,
    string $pestFileDir,
    string $pestFile
): void
```

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

### requirementFor

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-matcher-registry.md

Retrieves the pre-condition requirement for a specific matcher method.

```APIDOC
## requirementFor(string $methodName)

### Description
Returns the pre-condition requirement for a matcher method.

### Parameters
- **$methodName** (string) - Required - The assertion method name (e.g., 'each', 'toBeJson')

### Returns
- **?string** - One of REQUIREMENT_* constants or null if no requirement
```

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

### Breaking Out of Higher-Order Expectations

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Illustrates how to return to a standard Expectation type using the and() method.

```php
expect($items)->each()->toBeInt()->and('done')
// ->each() → HigherOrderExpectation<array, int>
// ->toBeInt() → HigherOrderExpectation<array, int>
// ->and('done') → Expectation<string>
```

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

### getType method definition

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Entry point for resolving expression types, dispatching to property or method handlers based on the AST node type.

```php
public function getType(Expr $expr, Scope $scope): ?Type
```

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

### TestCasePropertiesExtension getProperty method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Returns a property reflection for any property name on a TestCase class.

```php
public function getProperty(ClassReflection $classReflection, string $propertyName): PropertyReflection
```

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

### Check Code Style Without Applying Fixes

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Run this command to check code style using Rector and Pint without making any changes.

```bash
composer test:lint
```

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

### Empty group() Name

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

The `group()` method requires at least one non-empty, non-whitespace string argument. An empty string will cause an error.

```php
it('example', fn () => null)->group('');
// ✘ group() requires a non-empty string argument.
```

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

### Infer Dynamic Property Types

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/README.md

Properties assigned in beforeEach are correctly inferred by PHPStan.

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

it('accesses property', function () {
    $this->user->name;  // PHPStan knows it's User, not mixed
});
```

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

### Type Narrowing Assertions with expect()

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Shows how type-checking assertion methods like toBeString() and toBeInstanceOf() narrow the generic type parameter, allowing PHPStan to track the type through assertion chains.

```php
/** @var int|string $value */
$value = getValue();

expect($value)->toBeString();
// PHPStan now knows the expectation wraps a string

expect($value)->toBeInstanceOf(User::class);
// PHPStan now knows the expectation wraps a User
```

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

### Implement isFunctionSupported method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Checks if the provided function reflection and parameter correspond to a recognized Pest test or hook function.

```php
public function isFunctionSupported(
    FunctionReflection $functionReflection,
    ParameterReflection $parameter
): bool
```

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

### Method signature for getMethod

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

The signature for the getMethod implementation within the TestCallMethodsClassReflectionExtension.

```php
public function getMethod(ClassReflection $classReflection, string $methodName): MethodReflection
```

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

### Normalize file paths

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-file-discoverer.md

Converts paths to a canonical absolute format with consistent separators and casing.

```php
public function normalizePath(string $path): string
```

```php
$normalized = $discoverer->normalizePath('/app/tests/../tests/Pest.php');
// Returns: '/app/tests/pest.php' (or similar canonical form)

$normalized = $discoverer->normalizePath('tests\Pest.php');
// Returns: '/app/tests/Pest.php' (absolute, with forward slashes)
```

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

### Override Internal Services

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/configuration.md

Advanced configuration to override internal PestStan services.

```neon
services:
    -
        class: PestStan\Type\Pest\PestFunctionReturnTypeExtension
        tags:
            - phpstan.broker.dynamicFunctionReturnTypeExtension
```

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

### TestCasePropertiesExtension hasProperty method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Determines if the extension handles properties for a given class reflection.

```php
public function hasProperty(ClassReflection $classReflection, string $propertyName): bool
```

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

### Non-existent Symbol in coversClass()

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

PestStan verifies that symbols referenced in `coversClass()`, `coversTrait()`, and `coversFunction()` exist. Referencing a non-existent symbol will result in an error.

```php
it('covers something', function () { ... })->coversClass('App\Nonexistent\Service');
// ✘ Class App\Nonexistent\Service referenced in coversClass() does not exist.
```

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

### Extract description from Pest test function

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-function-detector.md

Retrieves the test description string from a function call, returning null for dynamic descriptions.

```php
// For: it('creates a post', function() { ... })
$desc = PestFunctionDetector::extractDescription($node);
// Returns: 'creates a post'

// For: it($dynamicName, function() { ... })
$desc = PestFunctionDetector::extractDescription($node);
// Returns: null (not a string literal)
```

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

### Type Narrowing Through Assertions

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/overview.md

Shows how assertion methods narrow the type of the expectation chain for PHPStan analysis.

```php
/** @var int|string $value */
$value = getValue();

expect($value)->toBeString();
// Now PHPStan knows: Expectation<string>
```

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

### Analyze Test Patterns

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/README.md

PestStan detects common issues like empty test bodies or impossible assertions.

```php
it('broken test', function () {});
// ✘ Empty test body

it('impossible', function () {
    expect(42)->toBeString();
    // ✘ Assertion is impossible
});

describe('suite', function () {
    // ✘ No tests in describe block
});
```

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

### Generic expect() Function Type Inference

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Demonstrates how PestStan infers the generic type of the expectation based on the argument passed to the expect() function.

```php
expect('hello');           // Expectation<string>
expect(42);                // Expectation<int>
expect(['a' => 1]);        // Expectation<array{a: int}>
expect($user);             // Expectation<User>
expect();                  // Expectation<null>
```

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

### Duplicate Test Description Detection

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Rule `pest.test.duplicateDescription` detects two tests within the same file having identical descriptions, which leads to runtime collisions.

```php
it('does something', fn () => expect(1)->toBe(1));
it('does something', fn () => expect(2)->toBe(2));
// ✘ A test with the description 'it does something' already exists in this file.
```

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

### PestDiagnostic Methods

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/types.md

Methods for converting PestDiagnostic instances to arrays or JSON-serializable formats.

```php
public function toArray(): array
```

```php
public function jsonSerialize(): array
```

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

### Check Code Style

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Performs a dry-run check of code style without applying any fixes. Use this to verify if the code adheres to the project's coding standards.

```bash
composer test:lint   # Check code style (dry-run)
```

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

### Define extractUsesBindings method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-config-reader.md

Extracts class bindings from uses() calls, supporting both directory-scoped and file-level patterns.

```php
private function extractUsesBindings(
    NodeFinder $nodeFinder,
    array $stmts,
    string $pestFileDir,
    string $pestFile
): void
```

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

### Chain Assertions

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/README.md

PestStan supports chained expectation methods.

```php
expect('hello')
    ->toBeString()
    ->and(42)
    ->toBeInt()
    ->and([1, 2])
    ->toHaveCount(2);
```

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

### Implement getTypeFromMethodCall method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/opposite-expectation-method-return-type-extension.md

Resolves the return type to ensure the original generic type is preserved after negation.

```php
public function getTypeFromMethodCall(
    MethodReflection $methodReflection,
    MethodCall $methodCall,
    Scope $scope
): Type
```

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

### Type-Safe and() Chaining

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Illustrates how the `and()` method correctly changes the generic type parameter, enabling type-safe assertion chains with multiple expectations.

```php
expect('hello')
    ->toBeString()       // Expectation<string>
    ->and(42)            // Expectation<int>
    ->toBeInt()          // Expectation<int>
    ->and(['a', 'b'])    // Expectation<array{string, string}>
    ->toHaveCount(2);    // Expectation<array{string, string}>
```

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

### Dynamic Property Inference

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/overview.md

Demonstrates how PestStan tracks types for properties assigned to $this within lifecycle hooks.

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

it('test', function () {
    $this->user->name;  // PHPStan knows type is User
});
```

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

### Consume PestStan Diagnostics

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/README.md

Convert diagnostic objects to arrays or JSON, and canonicalize identifiers for tool integration.

```php
// Get diagnostics in array form
$array = $diagnostic->toArray();

// Serialize to JSON
json_encode($diagnostic);

// Access canonical identifier
$canonical = PestDiagnosticIdentifiers::canonicalize($identifier);
```

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

### Suppress PestStan Rules

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/overview.md

Shows how to ignore specific PestStan rules using PHPStan's standard configuration format.

```neon
parameters:
    ignoreErrors:
        - identifier: pest.expectation.redundant
```

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

### Pest Expectation Method Type Narrowing

Source: https://github.com/mrpunyapal/peststan/blob/main/DEVELOPMENT.md

Demonstrates how type-narrowing assertion methods on Pest's Expectation object return a more specific type.

```php
Type-narrowing methods (toBeString, toBeInt, etc.) return Expectation<narrowedType>
All other assertion methods preserve the caller's generic type parameter
```

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

### Detect empty test closures

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/static-analysis-rules.md

Tests with empty closure bodies are flagged as incomplete, though todo tests without closures are permitted.

```php
it('does something'); // fine — todo test

it('does something', function () {});
// ✘ Test 'does something' has an empty closure body. Did you forget to add assertions?
```

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

### Implement isMethodSupported method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/opposite-expectation-method-return-type-extension.md

Checks if the method being called is declared on the Pest mixin class.

```php
public function isMethodSupported(MethodReflection $methodReflection): bool
```

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

### Retrieve matcher requirements

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-matcher-registry.md

Use requirementFor to determine if a matcher method requires a specific input type, such as iterable or string.

```php
$req = $registry->requirementFor('each');
// Returns: REQUIREMENT_ITERABLE

$req = $registry->requirementFor('toBeJson');
// Returns: REQUIREMENT_STRING

$req = $registry->requirementFor('toBe');
// Returns: null (no pre-condition)
```

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

### Handle multiple bindings

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Multiple uses() declarations result in an intersection type for $this.

```php
// Pest.php
uses(Trait1::class, Trait2::class)->in('Feature');

// Result: $this is Trait1&Trait2 (intersection type)
```

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

### Detect duplicate test descriptions

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/static-analysis-rules.md

Tests with identical descriptions at the top level of a file will collide during execution.

```php
it('does something', fn () => expect(1)->toBe(1));
it('does something', fn () => expect(2)->toBe(2));
// ✘ A test with the description 'it does something' already exists in this file.
```

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

### Implement getClosureThisTypeFromFunctionCall method

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/test-closure-this-type-extension.md

Resolves the specific $this type for a closure based on Pest configuration or default settings.

```php
public function getClosureThisTypeFromFunctionCall(
    FunctionReflection $functionReflection,
    FuncCall $functionCall,
    ParameterReflection $parameter,
    Scope $scope
): Type
```

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

### Empty Test Body Detection

Source: https://github.com/mrpunyapal/peststan/blob/main/README.md

Rule `pest.test.emptyClosure` detects tests with empty closure bodies. A `todo` test is considered fine.

```php
it('does something'); // fine — todo test
it('does something', function () {});
// ✘ Test 'does something' has an empty closure body. Did you forget to add assertions?
```

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

### Define Known Expectation Properties

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/higher-order-expectation-type-extension.md

Defines the list of properties on Expectation that do not trigger dynamic HigherOrderExpectation behavior.

```php
/** @var list<string> */
private const EXPECTATION_KNOWN_PROPERTIES = ['each', 'classes', 'traits', 'interfaces', 'enums'];
```

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

### Automatic $this Binding

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/overview.md

Illustrates how PestStan automatically binds the test case class to $this in test files.

```php
// In tests/Pest.php:
uses(Tests\TestCase::class)->in('Feature');

// In tests/Feature/ExampleTest.php:
it('works', function () {
    $this->get('/');  // PHPStan knows $this is Tests\TestCase
});
```

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

### Bind $this in Closures

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/README.md

PestStan ensures PHPStan understands the $this context within Pest tests.

```php
// tests/Pest.php
uses(Tests\TestCase::class)->in('Feature');

// tests/Feature/ExampleTest.php
it('can use test methods', function () {
    $this->get('/');  // PHPStan knows $this is Tests\TestCase
    $this->assertTrue(true);
});
```

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

### Check if node is a Pest function

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-function-detector.md

Use isPestFunction to verify if a given FuncCall node is a recognized Pest function.

```php
if (PestFunctionDetector::isPestFunction($node)) {
    // Process Pest function call
}
```

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

### Define Type Assertion Categories

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/expectation-matcher-registry.md

Constants representing the various type assertion categories supported by the registry.

```php
public const TYPE_STRING = 'string'
public const TYPE_INT = 'int'
public const TYPE_FLOAT = 'float'
public const TYPE_BOOL = 'bool'
public const TYPE_TRUE = 'true'
public const TYPE_FALSE = 'false'
public const TYPE_NULL = 'null'
public const TYPE_ARRAY = 'array'
public const TYPE_LIST = 'list'
public const TYPE_OBJECT = 'object'
public const TYPE_CALLABLE = 'callable'
public const TYPE_ITERABLE = 'iterable'
public const TYPE_NUMERIC = 'numeric'
public const TYPE_SCALAR = 'scalar'
public const TYPE_INSTANCE_OF = 'instanceof'
```

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

### Check if node is a test function

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/pest-function-detector.md

Use isTestFunction to identify test definition functions like it, test, or todo.

```php
if (PestFunctionDetector::isTestFunction($node)) {
    // This is a test definition
}
```

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

### PestHookPropertyReader Method Signature

Source: https://github.com/mrpunyapal/peststan/blob/main/_autodocs/additional-extensions.md

Signature for the getPropertyExprs method.

```php
public function getPropertyExprs(string $filePath): array
```
Tokens:
Raw