docs: document new v4.5 features

Author: nunomaduro

arch-testing.md

@@ -48,6 +48,7 @@ Granular expectations allow you to define specific architectural rules for your
 <div class="collection-method-list" markdown="1">
 
 - [`toBeAbstract()`](#expect-toBeAbstract)
+- [`toBeCasedCorrectly()`](#expect-toBeCasedCorrectly)
 - [`toBeClasses()`](#expect-toBeClasses)
 - [`toBeEnums()`](#expect-toBeEnums)
 - [`toBeIntBackedEnums()`](#expect-toBeIntBackedEnums)
@@ -104,6 +105,19 @@ arch('app')
     ->toBeAbstract();
 ```
 
+<a name="expect-toBeCasedCorrectly"></a>
+### `toBeCasedCorrectly()`
+
+The `toBeCasedCorrectly()` method may be used to ensure that all class names match their file and directory path casing, verifying PSR-4 autoloading compliance.
+
+```php
+arch('app')
+    ->expect('App')
+    ->toBeCasedCorrectly();
+```
+
+For example, if a class is named `App\Models\UserProfile`, this expectation verifies that the file is located at `app/Models/UserProfile.php` — and not `app/Models/Userprofile.php` or `app/models/UserProfile.php`.
+
 <a name="expect-toBeClasses"></a>
 ### `toBeClasses()`
 

cli-api-reference.md

@@ -34,6 +34,7 @@ In the preceding chapters of the Pest documentation, we have covered numerous CL
 - `--issue`: Output to standard output tests with the given issue number.
 - `--pr`: Output to standard output tests with the given pull request number.
 - `--pull-request`: Output to standard output tests with the given pull request number (alias for `--pr`).
+- `--flaky`: Output to standard output tests marked as flaky.
 - `--retry`: Run non-passing tests first and stop execution upon first error or failure.
 - `--list-suites` List available test suites.
 - `--testsuite <name>`: Only run tests from the specified test suite(s).
@@ -122,6 +123,8 @@ In the preceding chapters of the Pest documentation, we have covered numerous CL
 
 - `--coverage`: Generate code coverage report and output to standard output.
 - `--coverage --min=<value>`: Set the minimum required coverage percentage, and fail if not met.
+- `--coverage --exactly=<value>`: Set the exact required coverage percentage, and fail if not met.
+- `--coverage --only-covered`: Hide files with 0% coverage from the code coverage report.
 - `--coverage-clover <file>`: Write code coverage report in Clover XML format to file.
 - `--coverage-cobertura <file>`: Write code coverage report in Cobertura XML format to file.
 - `--coverage-crap4j <file>`: Write code coverage report in Crap4J XML format to file.

datasets.md

@@ -85,6 +85,36 @@ test('The generator produces only integers', function ($i) {
 });
 ```
 
+## Named Parameters
+
+When using datasets with associative arrays, Pest matches the dataset keys to the closure parameter names, regardless of order. This allows you to define your dataset in any key order and have the values automatically mapped to the correct parameters.
+
+```php
+it('has user data', function (string $email, string $name) {
+    expect($name)->toBeString();
+    expect($email)->toContain('@');
+})->with([
+    ['name' => 'Taylor', 'email' => 'taylor@laravel.com'],
+    ['name' => 'Nuno', 'email' => 'enunomaduro@gmail.com'],
+]);
+```
+
+In the example above, even though the dataset defines `name` before `email`, Pest maps them correctly to the closure parameters `$email` and `$name`.
+
+Named parameters also work with shared datasets and bound closures.
+
+```php
+dataset('users', [
+    ['name' => 'Taylor', 'email' => 'taylor@laravel.com'],
+    ['name' => 'Nuno', 'email' => 'enunomaduro@gmail.com'],
+]);
+
+it('has user data', function (string $email, string $name) {
+    expect($name)->toBeString();
+    expect($email)->toContain('@');
+})->with('users');
+```
+
 ## Bound Datasets
 
 Pest's bound datasets can be used to obtain a dataset that is resolved after the `beforeEach()` method of your tests. This is particularly useful in Laravel applications (or any other Pest integration) where you may need a dataset of `App\Models\User` models that are created after your database schema is prepared by the `beforeEach()` method.
@@ -176,6 +206,34 @@ When running the example above, Pest's output will contain a description of each
     <img src="/assets/img/datasets-businesshours.webp?1" style="--lines: 10" />
 </div>
 
+## Describe Blocks With Datasets
+
+You can attach a dataset to a `describe()` block, and all tests within that block will receive the dataset values.
+
+```php
+describe('user notifications', function () {
+    test('can send notification', function (string $channel) {
+        expect($channel)->toBeString();
+    });
+
+    test('can queue notification', function (string $channel) {
+        expect($channel)->toBeIn(['mail', 'sms']);
+    });
+})->with(['mail', 'sms']);
+```
+
+You can also use `beforeEach()->with()` inside a `describe()` block to apply a dataset to all tests within that scope.
+
+```php
+describe('user settings', function () {
+    beforeEach()->with([10, 20, 30]);
+
+    test('receives the dataset value', function (int $value) {
+        expect($value)->toBeGreaterThan(0);
+    });
+});
+```
+
 ## Repeating Tests
 
 In some cases, you may need to repeat a test multiple times for debugging purposes or to ensure that the test is stable. On these occasions, you may use the `repeat()` method to repeat a test a given number of times.

filtering-tests.md

@@ -17,6 +17,7 @@ This chapter will cover even more ways to filter which tests are executed by Pes
 
 - [`--bail`](#bail)
 - [`--dirty`](#dirty)
+- [`--flaky`](#flaky)
 - [`--filter`](#filter)
 - [`--group`](#group)
 - [`--exclude-group`](#exclude-group)
@@ -45,6 +46,52 @@ The `--dirty` option instructs Pest to only run tests that have uncommitted chan
 
 > Note that, due to a limitation in Pest, test cases written using the PHPUnit syntax will always be considered dirty.
 
+<a name="flaky"></a>
+### `--flaky`
+
+Some tests may occasionally fail due to external factors like network latency, timing issues, or third-party service instability. You can mark these tests as "flaky" using the `flaky()` method, and Pest will automatically retry them before reporting a failure.
+
+```php
+it('may have external dependencies', function () {
+    $response = Http::get('https://example.com/api');
+
+    expect($response->status())->toBe(200);
+})->flaky();
+```
+
+By default, `flaky()` retries the test up to **3 times**. You can customize the number of retries by passing the `tries` parameter.
+
+```php
+it('may have external dependencies', function () {
+    $response = Http::get('https://example.com/api');
+
+    expect($response->status())->toBe(200);
+})->flaky(tries: 5);
+```
+
+Between retries, Pest properly re-runs your `setUp` and `tearDown` lifecycle hooks, clears mock objects, and resets dynamic properties — ensuring each attempt starts from a clean state.
+
+Note that `flaky()` will not retry tests that are skipped, incomplete, or that throw an expected exception (via `->throws()`). It only retries on unexpected failures.
+
+The `flaky()` method can be combined with other test methods like `with()`, `repeat()`, and `describe()` blocks.
+
+```php
+it('works with datasets', function (string $url) {
+    $response = Http::get($url);
+
+    expect($response->status())->toBe(200);
+})->flaky(tries: 2)->with([
+    'https://example.com/api/users',
+    'https://example.com/api/posts',
+]);
+```
+
+To list all tests marked as flaky in your test suite, use the `--flaky` option.
+
+```bash
+./vendor/bin/pest --flaky
+```
+
 <a name="filter"></a>
 ### `--filter`
 

test-coverage.md

@@ -56,6 +56,20 @@ Or, you can use the `--exactly` option to enforce that the coverage results matc
 ./vendor/bin/pest --coverage --exactly=99.3
 ```
 
+## Hiding Uncovered Files
+
+When working on a large codebase, the coverage report can be noisy with many files showing 0% coverage. You can use the `--only-covered` option to hide files with no coverage from the report, allowing you to focus on the files that are partially covered.
+
+```bash
+./vendor/bin/pest --coverage --only-covered
+```
+
+This option can be combined with `--min` or `--exactly` for threshold enforcement.
+
+```bash
+./vendor/bin/pest --coverage --only-covered --min=90
+```
+
 ## Ignoring Code
 
 If there are certain sections of your application that cannot be tested and should be excluded from code coverage analysis, you can use `@codeCoverageIgnoreStart` and `@codeCoverageIgnoreEnd` comments in your source code to achieve this.