From 342e782027ccaa9d3fa107f2e206d127f0aae35e Mon Sep 17 00:00:00 2001
From: Willem-Jaap <willemjaapk@gmail.com>
Date: Thu, 18 Dec 2025 12:21:20 +0100
Subject: [PATCH] feat: add docs for file level only

---
 filtering-tests.md | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/filtering-tests.md b/filtering-tests.md
index aa01e92..1f13f7f 100644
--- a/filtering-tests.md
+++ b/filtering-tests.md
@@ -100,14 +100,42 @@ The `--retry` flag reorders your test suites by prioritizing the previously fail
 <a name="only"></a>
 ### `only()`
 
-If you want to run a specific test in your test suite, you can use the `only()` method.
+During development, you may want to focus on running specific tests while excluding all others. Pest provides two ways to do this: running only tests in a specific file, or running only a specific test within a file.
 
-```bash
+#### Running Only Tests in a File
+
+When working on a specific feature, you can mark all tests in a file to run exclusively by calling the `only()` function at the top of your test file:
+
+```php
+<?php
+
+only();
+
+test('first test', function () {
+    // This will run
+});
+
+test('second test', function () {
+    // This will also run
+});
+```
+
+All tests in files with `only()` will run, while tests in other files will be skipped.
+
+#### Running a Single Test
+
+To run only a specific test within a file, chain the `->only()` method to the test:
+
+```php
 test('sum', function () {
   $result = sum(1, 2);
 
   expect($result)->toBe(3);
 })->only();
+
+test('another test', function () {
+  // This will be skipped
+});
 ```
 
 ---