release: v2.24.1

[2.x] Add `throwsUnless`

.github/workflows/integration-tests.yml

@@ -20,7 +20,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Setup PHP
       uses: shivammathur/setup-php@v2

.github/workflows/static.yml

@@ -18,7 +18,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Setup PHP
       uses: shivammathur/setup-php@v2

.github/workflows/tests.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Setup PHP
       uses: shivammathur/setup-php@v2

README.md

@@ -32,7 +32,6 @@ We cannot thank our sponsors enough for their incredible support in funding Pest
 - [Codecourse](https://codecourse.com/)
 - [Laracasts](https://laracasts.com/)
 - [Localazy](https://localazy.com)
-- [Fathom Analytics](https://usefathom.com/)
 - [Meema](https://meema.io)
 - [Zapiet](https://www.zapiet.com)
 

composer.json

@@ -19,14 +19,14 @@
     "require": {
         "php": "^8.1.0",
         "brianium/paratest": "^7.3.0",
-        "nunomaduro/collision": "^7.9.0|^8.0.0",
+        "nunomaduro/collision": "^7.10.0|^8.0.0",
         "nunomaduro/termwind": "^1.15.1|^2.0.0",
         "pestphp/pest-plugin": "^2.1.1",
-        "pestphp/pest-plugin-arch": "^2.4.0",
-        "phpunit/phpunit": "^10.4.1"
+        "pestphp/pest-plugin-arch": "^2.4.1",
+        "phpunit/phpunit": "^10.4.2"
     },
     "conflict": {
-        "phpunit/phpunit": ">10.4.1",
+        "phpunit/phpunit": ">10.4.2",
         "sebastian/exporter": "<5.1.0",
         "webmozart/assert": "<1.11.0"
     },
@@ -76,7 +76,7 @@
         "test:type:coverage": "php bin/pest --type-coverage --min=100",
         "test:unit": "php bin/pest --colors=always --exclude-group=integration --compact",
         "test:inline": "php bin/pest --colors=always --configuration=phpunit.inline.xml",
-        "test:parallel": "php bin/pest --colors=always --exclude-group=integration --parallel --processes=10",
+        "test:parallel": "php bin/pest --colors=always --exclude-group=integration --parallel --processes=3",
         "test:integration": "php bin/pest --colors=always --group=integration",
         "update:snapshots": "REBUILD_SNAPSHOTS=true php bin/pest --colors=always --update-snapshots",
         "test": [

src/Console/Thanks.php

@@ -23,9 +23,10 @@ final class Thanks
      * @var array<string, string>
      */
     private const FUNDING_MESSAGES = [
-        'Star the project on GitHub' => 'https://github.com/pestphp/pest',
-        'Tweet about the project' => 'https://twitter.com/pestphp',
-        'Sponsor the project' => 'https://github.com/sponsors/nunomaduro',
+        'Star' => 'https://github.com/pestphp/pest',
+        'News' => 'https://twitter.com/pestphp',
+        'Videos' => 'https://youtube.com/@nunomaduro',
+        'Sponsor' => 'https://github.com/sponsors/nunomaduro',
     ];
 
     /**

src/Factories/Annotations/TestDox.php

@@ -15,12 +15,11 @@ final class TestDox implements AddsAnnotations
     public function __invoke(TestCaseMethodFactory $method, array $annotations): array
     {
         /*
-       * escapes docblock according to
-       * https://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc
-       *
-       * note: '@' escaping is not needed as it cannot be the first character of the line (it always starts with @testdox
-       */
-
+         * Escapes docblock according to
+         * https://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc
+         *
+         * Note: '@' escaping is not needed as it cannot be the first character of the line (it always starts with @testdox).
+         */
         assert($method->description !== null);
         $methodDescription = str_replace('*/', '{@*}', $method->description);
 

src/PendingCalls/TestCall.php

@@ -105,6 +105,24 @@ final class TestCall
         return $this;
     }
 
+    /**
+     * Asserts that the test throws the given `$exceptionClass` when called if the given condition is false.
+     *
+     * @param  (callable(): bool)|bool  $condition
+     */
+    public function throwsUnless(callable|bool $condition, string|int $exception, string $exceptionMessage = null, int $exceptionCode = null): self
+    {
+        $condition = is_callable($condition)
+            ? $condition
+            : static fn (): bool => $condition;
+
+        if (! $condition()) {
+            return $this->throws($exception, $exceptionMessage, $exceptionCode);
+        }
+
+        return $this;
+    }
+
     /**
      * Runs the current test multiple times with
      * each item of the given `iterable`.

src/Pest.php

@@ -6,7 +6,7 @@ namespace Pest;
 
 function version(): string
 {
-    return '2.23.2';
+    return '2.24.1';
 }
 
 function testDirectory(string $file = ''): string

tests/.pest/snapshots/Visual/Help/visual_snapshot_of_help_command_output.snap

@@ -1,5 +1,5 @@
 
-  Pest Testing Framework 2.23.2.  
+  Pest Testing Framework 2.24.1.  
 
   USAGE: pest <file> [options]  
 

tests/.pest/snapshots/Visual/Version/visual_snapshot_of_help_command_output.snap

@@ -1,3 +1,3 @@
 
-  Pest Testing Framework 2.23.2.  
+  Pest Testing Framework 2.24.1.  
 

tests/.snapshots/success.txt

@@ -215,6 +215,14 @@
   ✓ it can just define the code if given condition is true
   ✓ it can just define the message if given condition is 1
   ✓ it can just define the code if given condition is 1
+  ✓ it not catch exceptions if given condition is true
+  ✓ it catch exceptions if given condition is false
+  ✓ it catch exceptions and messages if given condition is false
+  ✓ it catch exceptions, messages and code if given condition is false
+  ✓ it can just define the message if given condition is false
+  ✓ it can just define the code if given condition is false
+  ✓ it can just define the message if given condition is 0
+  ✓ it can just define the code if given condition is 0
 
    PASS  Tests\Features\Expect\HigherOrder\methods
   ✓ it can access methods
@@ -1112,17 +1120,9 @@
    PASS  Tests\Helpers\TestInHelpers
   ✓ it executes tests in the Helpers directory
 
-   PASS  Tests\Hooks\AfterAllTest
-  ✓ global afterAll execution order
-  ✓ it only gets called once per file
-
    PASS  Tests\Hooks\AfterEachTest
   ✓ global afterEach execution order
 
-   PASS  Tests\Hooks\BeforeAllTest
-  ✓ global beforeAll execution order
-  ✓ it only gets called once per file
-
    PASS  Tests\Hooks\BeforeEachTest
   ✓ global beforeEach execution order
 
@@ -1352,4 +1352,4 @@
    WARN  Tests\Visual\Version
   - visual snapshot of help command output
 
-  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 19 skipped, 958 passed (2281 assertions)
+  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 19 skipped, 962 passed (2280 assertions)

tests/Features/Exceptions.php

@@ -59,3 +59,37 @@ it('can just define the message if given condition is 1', function () {
 it('can just define the code if given condition is 1', function () {
     throw new Exception('Something bad happened', 1);
 })->throwsIf(1, 1);
+
+it('not catch exceptions if given condition is true', function () {
+    $this->assertTrue(true);
+})->throwsUnless(true, Exception::class);
+
+it('catch exceptions if given condition is false', function () {
+    throw new Exception('Something bad happened');
+})->throwsUnless(function () {
+    return false;
+}, Exception::class);
+
+it('catch exceptions and messages if given condition is false', function () {
+    throw new Exception('Something bad happened');
+})->throwsUnless(false, Exception::class, 'Something bad happened');
+
+it('catch exceptions, messages and code if given condition is false', function () {
+    throw new Exception('Something bad happened', 1);
+})->throwsUnless(false, Exception::class, 'Something bad happened', 1);
+
+it('can just define the message if given condition is false', function () {
+    throw new Exception('Something bad happened');
+})->throwsUnless(false, 'Something bad happened');
+
+it('can just define the code if given condition is false', function () {
+    throw new Exception('Something bad happened', 1);
+})->throwsUnless(false, 1);
+
+it('can just define the message if given condition is 0', function () {
+    throw new Exception('Something bad happened');
+})->throwsUnless(0, 'Something bad happened');
+
+it('can just define the code if given condition is 0', function () {
+    throw new Exception('Something bad happened', 1);
+})->throwsUnless(0, 1);

tests/Features/TestCycle.php

@@ -8,16 +8,16 @@ $foo->beforeEach = false;
 $foo->afterEach = false;
 $foo->afterAll = false;
 
-beforeAll(function () {
+beforeAll(function () use ($foo) {
     $foo->beforeAll = true;
 });
-beforeEach(function () {
+beforeEach(function () use ($foo) {
     $foo->beforeEach = true;
 });
-afterEach(function () {
+afterEach(function () use ($foo) {
     $foo->afterEach = true;
 });
-afterAll(function () {
+afterAll(function () use ($foo) {
     $foo->afterAll = true;
 });
 

tests/Hooks/AfterAllTest.php

@@ -1,45 +0,0 @@
-<?php
-
-uses()->afterAll(function () {
-    expect($_SERVER['globalHook'])
-        ->toHaveProperty('afterAll')
-        ->and($_SERVER['globalHook']->afterAll)
-        ->toBe(0)
-        ->and($_SERVER['globalHook']->calls)
-        ->afterAll
-        ->toBe(1);
-
-    $_SERVER['globalHook']->afterAll = 1;
-    $_SERVER['globalHook']->calls->afterAll++;
-});
-
-afterAll(function () {
-    expect($_SERVER['globalHook'])
-        ->toHaveProperty('afterAll')
-        ->and($_SERVER['globalHook']->afterAll)
-        ->toBe(1)
-        ->and($_SERVER['globalHook']->calls)
-        ->afterAll
-        ->toBe(2);
-
-    $_SERVER['globalHook']->afterAll = 2;
-    $_SERVER['globalHook']->calls->afterAll++;
-});
-
-test('global afterAll execution order', function () {
-    expect($_SERVER['globalHook'])
-        ->not()
-        ->toHaveProperty('afterAll')
-        ->and($_SERVER['globalHook']->calls)
-        ->afterAll
-        ->toBe(0);
-});
-
-it('only gets called once per file', function () {
-    expect($_SERVER['globalHook'])
-        ->not()
-        ->toHaveProperty('afterAll')
-        ->and($_SERVER['globalHook']->calls)
-        ->afterAll
-        ->toBe(0);
-});

tests/Hooks/BeforeAllTest.php

@@ -1,55 +0,0 @@
-<?php
-
-use Pest\Plugins\Parallel;
-use Pest\Support\Str;
-
-// HACK: we have to determine our $_SERVER['globalHook-]>calls baseline. This is because
-// two other tests are executed before this one due to filename ordering.
-$args = $_SERVER['argv'] ?? [];
-$single = (isset($args[1]) && Str::endsWith(__FILE__, $args[1])) || Parallel::isWorker();
-$offset = $single ? 0 : 2;
-
-uses()->beforeAll(function () use ($offset) {
-    expect($_SERVER['globalHook'])
-        ->toHaveProperty('beforeAll')
-        ->and($_SERVER['globalHook']->beforeAll)
-        ->toBe(0)
-        ->and($_SERVER['globalHook']->calls)
-        ->beforeAll
-        ->toBe(1 + $offset);
-
-    $_SERVER['globalHook']->beforeAll = 1;
-    $_SERVER['globalHook']->calls->beforeAll++;
-});
-
-beforeAll(function () use ($offset) {
-    expect($_SERVER['globalHook'])
-        ->toHaveProperty('beforeAll')
-        ->and($_SERVER['globalHook']->beforeAll)
-        ->toBe(1)
-        ->and($_SERVER['globalHook']->calls)
-        ->beforeAll
-        ->toBe(2 + $offset);
-
-    $_SERVER['globalHook']->beforeAll = 2;
-    $_SERVER['globalHook']->calls->beforeAll++;
-});
-
-test('global beforeAll execution order', function () use ($offset) {
-    expect($_SERVER['globalHook'])
-        ->toHaveProperty('beforeAll')
-        ->and($_SERVER['globalHook']->beforeAll)
-        ->toBe(2)
-        ->and($_SERVER['globalHook']->calls)
-        ->beforeAll
-        ->toBe(3 + $offset);
-});
-
-it('only gets called once per file', function () use ($offset) {
-    expect($_SERVER['globalHook'])
-        ->beforeAll
-        ->toBe(2)
-        ->and($_SERVER['globalHook']->calls)
-        ->beforeAll
-        ->toBe(3 + $offset);
-});

tests/Visual/Parallel.php

@@ -16,7 +16,7 @@ $run = function () {
 
 test('parallel', function () use ($run) {
     expect($run('--exclude-group=integration'))
-        ->toContain('Tests:    1 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 15 skipped, 947 passed (2266 assertions)')
+        ->toContain('Tests:    1 deprecated, 4 warnings, 5 incomplete, 2 notices, 13 todos, 15 skipped, 951 passed (2265 assertions)')
         ->toContain('Parallel: 3 processes');
 })->skipOnWindows();