From 13b038d21a48b44cffb844a1f0008a70c779ca86 Mon Sep 17 00:00:00 2001
From: Daniel <daniel@sysanalyst.eu>
Date: Wed, 17 Jan 2024 12:54:43 +0100
Subject: [PATCH 1/2] Add example of fail() to Custom Expectation

---
 custom-expectations.md | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/custom-expectations.md b/custom-expectations.md
index ddd8c1c..7efae40 100644
--- a/custom-expectations.md
+++ b/custom-expectations.md
@@ -12,7 +12,7 @@ Custom expectations are usually defined in the `tests/Pest.php` file, but you ca
 For example, suppose you are testing a number utility library and you need to frequently assert that numbers fall within a given range. In this case, you might create a custom expectation called `toBeWithinRange()`:
 
 ```php
-// Pest.php or Expectations.php...
+// Pest.php or Expectations.php
 expect()->extend('toBeWithinRange', function (int $min, int $max) {
     return $this->toBeGreaterThanOrEqual($min)
                 ->toBeLessThanOrEqual($max);
@@ -35,7 +35,7 @@ expect()->extend('toBeWithinRange', function (int $min, int $max) {
 Of course, you probably want users to have the ability to "chain" expectations together with your custom expectation. To achieve this, ensure your custom expectation includes a `return $this` statement.
 
 ```php
-// Pest.php or Expectations.php...
+// Pest.php or Expectations.php
 expect()->extend('toBeWithinRange', function (int $min, int $max) {
     // Assertions based on `$this->value` and the given arguments...
 
@@ -51,6 +51,25 @@ test('numeric ranges', function () {
 });
 ```
 
+Sometimes, you may need to trigger a test failure in your Custom Expectation. To do so, use the `test()` method in combination with the [fail()](/docs/exceptions) method.
+
+```php
+// Pest.php or Expectations.php
+expect()->extend('toBeDivisibleBy', function (int $divisor) {
+    if ($divisor === 0) {
+        test()->fail('The divisor cannot be 0.');
+    }
+
+    return expect($this->value % $divisor)->toBe(0);
+});
+
+// Tests/Unit/ExampleTest.php
+test('numeral division', function () {
+    expect(10)->toBeDivisibleBy(2); // Pass
+    expect(10)->toBeDivisibleBy(0); // Fail "The divisor cannot be 0."
+});
+```
+
 ## Intercept Expectations
 
 Although it is considered an advanced practice, you can override existing expectations with your own implementation via the `intercept()` method. When using this method, the existing expectation will be fully substituted if the expectation value is of the specified type. For example, you can replace the `toBe()` expectation to check if two objects of the `Illuminate\Database\Eloquent\Model` type have the same `id`.

From 8d1def58eb3cbf41875cfe85263195a26dbe8774 Mon Sep 17 00:00:00 2001
From: Dan <79267265+dansysanalyst@users.noreply.github.com>
Date: Wed, 17 Jan 2024 13:15:03 +0100
Subject: [PATCH 2/2] fix link

Co-authored-by: Owen Voke <development@voke.dev>
---
 custom-expectations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/custom-expectations.md b/custom-expectations.md
index 7efae40..0a355a7 100644
--- a/custom-expectations.md
+++ b/custom-expectations.md
@@ -51,7 +51,7 @@ test('numeric ranges', function () {
 });
 ```
 
-Sometimes, you may need to trigger a test failure in your Custom Expectation. To do so, use the `test()` method in combination with the [fail()](/docs/exceptions) method.
+Sometimes, you may need to trigger a test failure in your Custom Expectation. To do so, use the `test()` method in combination with the [`fail()`](/docs/exceptions) method.
 
 ```php
 // Pest.php or Expectations.php