Merge pull request #42 from jordanbrauer/reusable-hooks

reusable/shared setup & teardown documentation

setup-and-teardown.md

@@ -7,6 +7,7 @@ description: Setup and Teardown
 
 - [Overview](#overview)
 - [Setup and Teardown](#setup-and-teardown)
+- [Reusable (Shared) Setup and Teardown](#reusable-shared-setup-and-teardown)
 - [Example](#example)
 
 <a name="overview"></a>
@@ -147,6 +148,23 @@ test('bar', function () {
 // afterAll
 ```
 
+<a name="reusable-shared-setup-and-teardown"></a>
+## Reusable (Shared) Setup and Teardown
+
+At some point, you may need (or want) to share some kind of test scenario setup
+or teardown procedure. Doing this is very easy, using the exact same tools used
+in the previous section, only this time we combine it with the
+[`uses()` function](/docs/underlying-test-case#uses)!
+
+```php
+// Pest.php
+uses()->in('Feature/Dashboard')
+    ->beforeEach(fn () => $this->actingAs(User::first()));
+```
+
+**_All_ setup & teardown methods** described on this page are available for
+reuse/sharing like this! `beforeEach()` is only used as one example.
+
 <a name="example"></a>
 ## Example
 
@@ -173,6 +191,50 @@ test('example 2', fn () => dump('test bar'));
 // "afterAll"
 ```
 
+Again! Except this time we will use all the global (reusable/shared hooks) we
+possibly can, and combine them with the local hooks in the previous example to
+show execution order.
+
+```php
+// tests/Pest.php
+uses()
+    ->beforeAll(fn () => dump(1))
+    ->beforeEach(fn () => dump(2))
+    ->afterEach(fn () => dump(3))
+    ->afterAll(fn () => dump(4))
+    ->in('Unit');
+```
+
+```php
+// tests/Unit/MyTest.php
+uses()
+    ->beforeAll(fn () => dump('a'))
+    ->beforeEach(fn () => dump('b'))
+    ->afterEach(fn () => dump('c'))
+    ->afterAll(fn () => dump('d'));
+
+beforeAll(fn () => dump('i'));
+beforeEach(fn () => dump('ii'));
+afterEach(fn () => dump('iii'));
+afterAll(fn () => dump('iv'));
+
+test('order', fn () => dump('foo'));
+
+// 1
+// a
+// i
+// 2
+// b
+// ii
+// foo
+// 3
+// c
+// iii
+// 4
+// d
+// iv
+```
+
 ---
 
 Next section: [Higher Order Tests →](/docs/higher-order-tests)

underlying-test-case.md

@@ -26,9 +26,10 @@ it('has home', function () {
 In real-world applications, you may have to change it, and for that, you
 can call the `uses` function:
 
+<a name="uses"></a>
 ### `uses()`
 
-The `uses` function binds a class and/or trait to your test files.
+The `uses` function binds a class, trait and/or closure to your test files.
 This is how you would bind a trait to your current file:
 
 ```php
@@ -40,7 +41,8 @@ use Illuminate\Foundation\Testing\RefreshDatabase;
 uses(RefreshDatabase::class);
 ```
 
-The `in()` function lets you use the given class and/or trait recursively inside the specified folder:
+The `in()` function lets you use the given class, trait, or closure recursively
+inside the specified folder:
 
 ```php
 <?php
@@ -64,6 +66,10 @@ uses(TestCase::class)->in('Feature');
 
 // Uses the given trait in the "Unit" folder recursively
 uses(RefreshDatabase::class)->in('Unit');
+
+// Uses the given `beforeEach` setup closure in the "Regression" folder recursively
+// the same can be done for `beforeall`, `afterEach` and `afterAll`
+uses()->beforeEach(fn () => dump('foo'))->in('Regression');
 ```