From 2e81bc4dbdf4021fb5c7c95f044f77bd318e22cd Mon Sep 17 00:00:00 2001
From: jordanbrauer <18744334+jordanbrauer@users.noreply.github.com>
Date: Tue, 4 May 2021 18:56:31 -0500
Subject: [PATCH] add some documentation for reusable/shared setup & teardown
hooks
---
setup-and-teardown.md | 62 +++++++++++++++++++++++++++++++++++++++++
underlying-test-case.md | 10 +++++--
2 files changed, 70 insertions(+), 2 deletions(-)
diff --git a/setup-and-teardown.md b/setup-and-teardown.md
index ffb5682..f286ae2 100644
--- a/setup-and-teardown.md
+++ b/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)
@@ -147,6 +148,23 @@ test('bar', function () {
// afterAll
```
+
+## 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.
+
## 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)
diff --git a/underlying-test-case.md b/underlying-test-case.md
index f07608c..f2400b0 100644
--- a/underlying-test-case.md
+++ b/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:
+
### `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
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');
```