@@ -11,14 +11,13 @@ description: Pest's PHPStan plugin teaches PHPStan about Pest, providing accurat
 
 Pest's PHPStan plugin teaches PHPStan about Pest. It provides accurate type inference for your tests and expectations, and adds a set of Pest-specific rules that catch common mistakes before you run your suite.
 
-To get started, require the plugin via Composer along with PHPStan:
+To get started, require the plugin via Composer:
 
 ```bash
 composer require pestphp/pest-plugin-phpstan --dev
-composer require phpstan/phpstan --dev
 ```
 
-If you use [`phpstan/extension-installer`](https://github.com/phpstan/extension-installer), the plugin is registered automatically. Otherwise, include the extension in your `phpstan.neon` configuration file:
+As the plugin depends on PHPStan itself, this command will also install PHPStan in your project. If you use [`phpstan/extension-installer`](https://github.com/phpstan/extension-installer), the plugin is registered automatically. Otherwise, include the extension in your `phpstan.neon` configuration file:
 
 ```neon
 includes:
@@ -31,76 +30,120 @@ Then, analyze your `tests` directory as usual:
 vendor/bin/phpstan analyse tests
 ```
 
+There is no configuration to maintain. The plugin reads your `Pest.php` files directly — both the `uses(TestCase::class)->in(...)` and `pest()->extend(...)->use(...)->in(...)` styles — and resolves the right test case for each file automatically. The targets given to `in()` behave exactly as they do in Pest: relative or absolute paths, glob patterns, and single files are all supported.
+
 ---
 
-## Configuration
+## Type Inference
 
-To get the most accurate results, tell the plugin about the base test case your tests extend. This allows PHPStan to correctly resolve `$this`, along with any custom methods and properties, inside your test closures:
+Once installed, the plugin makes PHPStan aware of Pest's dynamic API. As a result, analyzing your test suite becomes as accurate as analyzing your application code.
 
-```neon
-parameters:
-    peststan:
-        testCaseClass: Tests\TestCase
+### The `$this` Instance
+
+Inside test and hook closures, `$this` resolves to the test case bound to that file through your Pest configuration. For example, given the following `Pest.php` file:
+
+```php
+pest()->extend(Tests\TestCase::class)
+    ->use(Illuminate\Foundation\Testing\RefreshDatabase::class)
+    ->in('Feature');
 ```
 
-By default, `testCaseClass` is set to `PHPUnit\Framework\TestCase`.
+Any test within the `Feature` directory will see `$this` typed as `Tests\TestCase`, along with all of its methods and properties:
 
-If your Pest configuration lives outside the default `tests/Pest.php` location, or you have multiple configuration files, you may point the plugin at them so it can resolve globally applied traits and test cases:
+```php
+it('has a home page', function () {
+    $this->get('/')->assertOk(); // $this is Tests\TestCase
+});
+```
 
-```neon
-parameters:
-    peststan:
-        testCaseClass: Tests\TestCase
-        pestConfigFiles:
-            - tests/Pest.php
-            - tests/Feature/Pest.php
+Of course, a per-file `uses()` call takes precedence over the directory binding, exactly as it does at runtime.
+
+### Custom Properties
+
+Properties you assign in a `beforeEach()` hook are recognized and typed on `$this` in your tests — whether the hook lives in the test file itself or is attached to your Pest configuration:
+
+```php
+beforeEach(function () {
+    $this->user = User::factory()->create();
+});
+
+it('can update the profile', function () {
+    $this->user; // App\Models\User
+});
 ```
 
----
+If a property is assigned in multiple hooks, its type will be the union of every assigned value. You may also guide the inference with a standard `@var` annotation on the assignment.
 
-## Type Inference
+### Expectation Chains
+
+The `expect()` function returns a generic `Expectation`, so every matcher knows the exact value it is asserting against. In addition, type-checking matchers narrow the value as the chain progresses:
 
-Once installed, the plugin makes PHPStan aware of Pest's dynamic API. As a result, analyzing your test suite becomes as accurate as analyzing your application code. Among other things, the plugin understands:
+```php
+/** @var int|string $value */
+expect($value)   // Expectation<int|string>
+    ->toBeInt(); // Expectation<int>
+```
+
+The value's type continues to flow through the entire expectation API, including `->and(...)` and `->not`, and matchers like `toBeInstanceOf()` narrow the value to the given class.
+
+### Higher Order Expectations
 
-- The type flowing through an `expect()` chain, so matchers such as `toHaveLength()` or `toHaveKey()` know the value they are asserting against.
-- The `$this` instance inside test and hook closures, resolving to your configured `testCaseClass` along with its methods and properties.
-- Higher order expectations, such as `expect($user)->name->toBe('Nuno')`.
-- Properties and methods shared across your tests through `pest()->extend()` and `uses()`.
+[Higher order expectations](/docs/higher-order-testing) are fully typed as well. When you access a property or call a method on an expectation, the plugin resolves its type from the underlying value — and after each assertion, the chain returns to the original value, exactly as it does at runtime:
+
+```php
+expect($user)
+    ->name->toBe('Nuno')
+    ->email->toContain('@');
+```
 
-This means PHPStan can flag genuine mistakes in your tests, like calling a string matcher on an integer, that would otherwise only surface at runtime.
+Similarly, public methods chained directly onto `it()` or `test()` — higher order tests — resolve against your bound test case, so a call like `it('has users')->actingAsAdmin()` is understood.
 
 ---
 
 ## Rules
 
-In addition to type inference, the plugin registers a number of rules that detect mistakes specific to Pest. Each reported error carries a stable identifier (for example, `pest.test.staticClosure`) so you may ignore it precisely when needed.
+In addition to type inference, the plugin registers a number of rules that detect mistakes specific to Pest. Each reported error carries a stable identifier, so you may ignore any rule precisely via PHPStan's standard `ignoreErrors` configuration:
+
+```neon
+parameters:
+    ignoreErrors:
+        - identifier: pest.expectation.redundant
+```
 
 ### Impossible Expectations
 
-Reports expectations that can never pass because the value's type is incompatible with the matcher:
+> Identifier: `pest.expectation.impossible`
+
+Reports type assertions that can never pass because the value's type is incompatible with the matcher:
 
 ```php
-expect(10)->toStartWith('1'); // int can never satisfy toStartWith()
+expect(10)->toBeString(); // an int can never be a string
 ```
 
 ### Redundant Expectations
 
-Reports expectations that are always true because the value's type already guarantees the assertion:
+> Identifier: `pest.expectation.redundant`
+
+Reports type assertions that are always true because the value's type already guarantees them:
 
 ```php
-expect('pest')->toBeString(); // $value is already known to be a string
+expect('pest')->toBeString(); // the value is already known to be a string
 ```
 
 ### Matcher Value Types
 
-Reports matchers called on a value that does not meet their requirements, such as a string, iterable, or countable value:
+> Identifiers: `pest.expectation.requiresString`, `pest.expectation.requiresIterable`, `pest.expectation.requiresCountableOrIterable`
+
+Reports matchers called on a value that does not meet their requirements. For instance, string matchers such as `toStartWith()` require a string, while `toHaveCount()` requires a countable or iterable value:
 
 ```php
-expect(42)->toHaveLength(2); // toHaveLength() requires a string
+expect(10)->toStartWith('1'); // toStartWith() requires a string
 ```
 
 ### Static Test Closures
 
+> Identifier: `pest.test.staticClosure`
+
 Reports test and hook closures declared as `static`, which prevents Pest from binding the test case instance to `$this`:
 
 ```php
@@ -111,44 +154,82 @@ it('does something', static function () { // remove the "static" keyword
 
 ### `$this` In `beforeAll()` And `afterAll()`
 
-Reports usage of `$this` inside `beforeAll()` and `afterAll()`, which run in a static context where the test case instance is not available.
+> Identifiers: `pest.lifecycle.beforeAllThisUsage`, `pest.lifecycle.afterAllThisUsage`
+
+Reports usage of `$this` inside `beforeAll()` and `afterAll()`, which run in a static context where the test case instance is not available, suggesting `beforeEach()` or `afterEach()` instead.
 
 ### Disallowed Calls In `describe()`
 
-Reports hooks that cannot be used directly inside a `describe()` block, such as `beforeAll()` and `afterAll()`, suggesting the correct alternative.
+> Identifiers: `pest.lifecycle.beforeAllDisallowed`, `pest.lifecycle.afterAllDisallowed`
+
+Reports `beforeAll()` and `afterAll()` calls made inside a `describe()` block, where they are not supported, suggesting the correct alternative.
 
 ### Describe Without Tests
 
-Reports `describe()` blocks that contain no tests.
+> Identifier: `pest.describe.withoutTests`
+
+Reports `describe()` blocks that contain no tests. Tests created dynamically — for example, inside a loop or a condition — are counted as you would expect.
 
 ### Duplicate Test Descriptions
 
-Reports two tests sharing the same description within a single file.
+> Identifier: `pest.test.duplicateDescription`
+
+Reports two tests sharing the same description within a single file. Descriptions given to `it()` are prefixed with "it", exactly as Pest does at runtime, so `it('works')` and `test('it works')` are considered duplicates.
 
 ### Empty Test Closures
 
+> Identifier: `pest.test.emptyClosure`
+
 Reports tests with an empty closure body, suggesting you add assertions or chain `->todo()` to mark the test as pending.
 
 ### Invalid Repeat Value
 
+> Identifier: `pest.execution.invalidRepeatValue`
+
 Reports `repeat()` calls with a value that is not greater than `0`.
 
 ### Invalid Group Names
 
+> Identifier: `pest.group.invalidName`
+
 Reports `group()` calls that are missing a non-empty string argument.
 
 ### Redundant Local Uses
 
-Reports `uses()` calls in a test file for a trait or test case that is already applied globally through your Pest configuration.
+> Identifier: `pest.config.redundantLocalUse`
+
+Reports `uses()` and `pest()->use()` calls in a test file for a trait or test case that is already applied to that file globally through your Pest configuration:
+
+```php
+// tests/Pest.php
+pest()->extend(TestCase::class)->use(RefreshDatabase::class)->in('Feature');
+
+// tests/Feature/ExampleTest.php
+uses(RefreshDatabase::class); // already applied through tests/Pest.php
+```
 
 ### Invalid `throws()` Exceptions
 
-Reports `throws()` calls that reference a class that does not exist or is not a `Throwable`.
+> Identifiers: `pest.throws.classNotFound`, `pest.throws.invalidException`
+
+Reports `throws()` calls that reference a class that does not exist or is not a `Throwable`. Of course, passing a plain string as the expected exception message is perfectly valid, and the plugin will not flag it:
+
+```php
+it('rejects invalid input', function () {
+    // ...
+})->throws(ValidationException::class);
+
+it('fails gracefully', function () {
+    // ...
+})->throws('Something went wrong'); // treated as the expected message
+```
 
 ### Missing `covers()` References
 
-Reports `covers()` calls that reference a class or function that does not exist.
+> Identifiers: `pest.covers.classNotFound`, `pest.covers.functionNotFound`
+
+Reports `coversClass()`, `coversTrait()`, and `coversFunction()` calls that reference a class, trait, or function that does not exist.
 
 ---
 
-Now that you know how to add static analysis to your test suite, let's explore the wider ecosystem of plugins that can enhance your Pest experience: [Plugins](/docs/plugins)
+In this chapter, we have discussed how Pest's PHPStan plugin brings accurate static analysis to your test suite. In the following chapter, we explore the wider ecosystem of plugins that can enhance your Pest experience: [Plugins →](/docs/plugins)