Closes #5300

ChangeLog-10.1.md

@@ -13,6 +13,7 @@ All notable changes of the PHPUnit 10.1 release series are documented in this fi
 * [#5237](https://github.com/sebastianbergmann/phpunit/issues/5237): Implement `IgnoreClassForCodeCoverage`, `IgnoreMethodForCodeCoverage`, and `IgnoreFunctionForCodeCoverage` attributes
 * [#5293](https://github.com/sebastianbergmann/phpunit/issues/5293): Allow to limit the reporting of deprecations, notices, and warnings to specified directories
 * [#5294](https://github.com/sebastianbergmann/phpunit/issues/5294): Introduce `<source>` XML configuration element to configure "your code"
+* [#5300](https://github.com/sebastianbergmann/phpunit/issues/5300): `TestCase::transformException()` hook method
 * `TestCase::createConfiguredStub()` was added as an analogon to `TestCase::createConfiguredMock()`
 * The `PHPUnit\Event\TestRunner\ExecutionAborted` event is now emitted when the execution of tests is stopped due to `stopOn*` attributes on the `<phpunit>` XML configuration element or due to `--stop-on-*` CLI options
 

src/Framework/TestCase.php

@@ -671,7 +671,7 @@ final public function runBare(): void
                     null
                 );
             } else {
-                $e = $_e;
+                $e = $this->transformException($_e);
 
                 $this->status = TestStatus::error($e->getMessage());
 
@@ -1465,6 +1465,11 @@ protected function getObjectForTrait(string $traitName, array $arguments = [], s
         );
     }
 
+    protected function transformException(Throwable $t): Throwable
+    {
+        return $t;
+    }
+
     /**
      * This method is called when a test method did not execute successfully.
      *

tests/end-to-end/_files/transform-exception-hook-method/phpunit.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../../../phpunit.xsd"
+         bootstrap="src/autoload.php">
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <source filterDeprecations="true" filterNotices="true" filterWarnings="true">
+        <include>
+            <directory suffix=".php">src</directory>
+        </include>
+    </source>
+</phpunit>

tests/end-to-end/_files/transform-exception-hook-method/src/OriginalException.php

@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\TestFixture\TransformExceptionHookMethod;
+
+use RuntimeException;
+
+final class OriginalException extends RuntimeException
+{
+}

tests/end-to-end/_files/transform-exception-hook-method/src/TransformedException.php

@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\TestFixture\TransformExceptionHookMethod;
+
+use RuntimeException;
+
+final class TransformedException extends RuntimeException
+{
+}

tests/end-to-end/_files/transform-exception-hook-method/src/autoload.php

@@ -0,0 +1,12 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+require __DIR__ . '/OriginalException.php';
+
+require __DIR__ . '/TransformedException.php';

tests/end-to-end/_files/transform-exception-hook-method/tests/Test.php

@@ -0,0 +1,26 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\TestFixture\TransformExceptionHookMethod;
+
+use PHPUnit\Framework\TestCase;
+use Throwable;
+
+final class Test extends TestCase
+{
+    public function testOne(): void
+    {
+        throw new OriginalException('original message');
+    }
+
+    protected function transformException(Throwable $t): Throwable
+    {
+        return new TransformedException('transformed message');
+    }
+}

tests/end-to-end/generic/transform-exception-hook-method.phpt

@@ -0,0 +1,30 @@
+--TEST--
+https://github.com/sebastianbergmann/phpunit/issues/5300
+--FILE--
+<?php declare(strict_types=1);
+$_SERVER['argv'][] = '--do-not-cache-result';
+$_SERVER['argv'][] = '--configuration';
+$_SERVER['argv'][] = __DIR__ . '/../_files/transform-exception-hook-method';
+
+require_once __DIR__ . '/../../bootstrap.php';
+
+(new PHPUnit\TextUI\Application)->run($_SERVER['argv']);
+--EXPECTF--
+PHPUnit %s by Sebastian Bergmann and contributors.
+
+Runtime: %s
+Configuration: %s
+
+E                                                                   1 / 1 (100%)
+
+Time: %s, Memory: %s
+
+There was 1 error:
+
+1) PHPUnit\TestFixture\TransformExceptionHookMethod\Test::testOne
+PHPUnit\TestFixture\TransformExceptionHookMethod\TransformedException: transformed message
+
+%s/Test.php:24
+
+ERRORS!
+Tests: 1, Assertions: 0, Errors: 1.