diff --git a/bridge/rector/FEATURE_PARITY.md b/bridge/rector/FEATURE_PARITY.md index d03bad20..4e1540f1 100644 --- a/bridge/rector/FEATURE_PARITY.md +++ b/bridge/rector/FEATURE_PARITY.md @@ -100,11 +100,14 @@ Done since the first cut: **structural class/method conversion** (Testo ↔ PHPU `#[\PHPUnit\Framework\Attributes\Test]` attribute is renamed to `#[\Testo\Test]`, a `@test` docblock annotation is dropped and replaced by the attribute, and a bare `test`-prefixed method simply gains the attribute (idempotent — a method already carrying `#[\Testo\Test]` is left alone); a trait's -non-abstract test methods gain it the same way. `parent::method();` statements that resolve into -PHPUnit are dropped, while calls reaching a method of a converted local base stay; a `parent::` call -to a static assertion of PHPUnit's `Assert` becomes `\PHPUnit\Framework\Assert::assertX()`, which the -assertion rules convert when Testo maps it and which stays a valid PHPUnit call otherwise (a -`TestCase` hook such as `assertPostConditions()` is dropped with the rest). The mirror +non-abstract test methods gain it the same way. Calls reaching a method of a converted local base +stay, while `parent::method();` statements that resolve into PHPUnit, which would no longer compile, +are rewritten: a call to a `TestCase` hook (`setUp()`, `tearDown()`, `assertPostConditions()` and the +like), or to the PHPUnit method its enclosing method overrides, is dropped; a call to a static +assertion of PHPUnit's `Assert` becomes `\PHPUnit\Framework\Assert::assertX()`, which the assertion +rules convert when Testo maps it and which stays a valid PHPUnit call otherwise; any other call, such +as `parent::markTestSkipped()` or `parent::expectException()`, becomes `self::`/`$this->` and converts +like that spelling. An anonymous class extending `TestCase` directly is handled the same way. The mirror `TestClassToTestCaseRector` (Testo → PHPUnit) adds `extends \PHPUnit\Framework\TestCase` and, for a class-level `#[\Testo\Test]`, removes it and adds a per-method `#[\PHPUnit\Framework\Attributes\Test]` to every public, non-static, `void`/`never` method (mirroring Testo's locator, so static/`iterable` diff --git a/bridge/rector/config/phpunit-to-testo/parent_behaviour_calls_converted.php.inc b/bridge/rector/config/phpunit-to-testo/parent_behaviour_calls_converted.php.inc new file mode 100644 index 00000000..119be2c3 --- /dev/null +++ b/bridge/rector/config/phpunit-to-testo/parent_behaviour_calls_converted.php.inc @@ -0,0 +1,48 @@ +` for the skip and expectation rules to + * convert. A call whose result is used is left for the manual pass. An anonymous class that + * extends `TestCase` directly is handled the same way; one on a project base is left untouched. * * "Test method" mirrors PHPUnit's own discovery: a method carrying the PHPUnit * `#[\PHPUnit\Framework\Attributes\Test]` attribute, a method with a `@test` docblock @@ -58,8 +65,8 @@ * `extends` and its `#[\Override]` attributes — the base is still there, converted on its own — * and only gains `#[\Testo\Test]` on its test methods. Without them Testo would not discover the * subclass's tests at all. Its `parent::` calls to a PHPUnit method the base does not override are - * dropped as well. A base that cannot be resolved, or does not lead to `TestCase`, leaves the class - * untouched. + * rewritten the same way. A base that cannot be resolved, or does not lead to `TestCase`, leaves the + * class untouched. * * A base from outside the processed paths, such as a framework's test case in vendor, stays a * PHPUnit class. Its subclasses are converted all the same, keep their `parent::` calls, and the @@ -82,6 +89,21 @@ final class ExtendsTestCaseToTestoRector extends AbstractRector { use OriginalTokens; + /** + * `TestCase` methods whose `parent::` call only reaches PHPUnit's own plumbing; Testo runs the + * overriding method on its own, so the call has nothing left to do. + */ + private const DROPPED_HOOKS = [ + '__construct', + 'setup', + 'teardown', + 'setupbeforeclass', + 'teardownafterclass', + 'assertpreconditions', + 'assertpostconditions', + 'onnotsuccessfultest', + ]; + public function __construct( private readonly PhpDocInfoFactory $phpDocInfoFactory, private readonly PhpDocTagRemover $phpDocTagRemover, @@ -153,10 +175,11 @@ public function refactor(Node $node): ?Node # Indirect subclass: the base stays, only discovery needs the attribute. $vendorBase = $this->testCaseClass->phpunitBaseFromVendor($node); + $base = $vendorBase === null ? $this->base($node) : null; $changed = false; foreach ($node->getMethods() as $method) { $method->isPublic() && $this->markTestMethod($method) and $changed = true; - $vendorBase === null && $this->removePhpunitParentCalls($node, $method) and $changed = true; + $base !== null && $this->rewritePhpunitParentCalls($base, $method) and $changed = true; } $vendorBase !== null && $vendorBase['direct'] && $this->skipOnVendorBase($node, $vendorBase['name']) @@ -165,13 +188,14 @@ public function refactor(Node $node): ?Node return $changed ? $node : null; } + $base = $this->base($node); $node->extends = null; $interfaces = $this->nodeNameResolver->getNames($node->implements); foreach ($node->getMethods() as $method) { $method->isPublic() and $this->markTestMethod($method); $this->isDeclaredByInterface($method, $interfaces) or $this->removeOverrideAttribute($method); - $this->removePhpunitParentCalls($node, $method); + $this->rewritePhpunitParentCalls($base, $method); } return $node; @@ -209,27 +233,46 @@ private function skipOnVendorBase(Class_ $class, string $vendorBase): bool } /** - * Drops the `parent::method()` statements that resolve into PHPUnit, which the converted chain no - * longer extends: without a parent PHP rejects `parent` at compile time, and on a converted base + * The class's direct base as loaded from source, read from the name it extends before its + * `extends` is removed: an anonymous class has no name of its own to reflect. + * + * @return ClassReflection|null Null when the base cannot be resolved. + */ + private function base(Class_ $class): ?ClassReflection + { + $base = $class->extends === null ? null : $this->getName($class->extends); + + return $base !== null && $this->reflectionProvider->hasClass($base) + ? $this->reflectionProvider->getClass($base) + : null; + } + + /** + * Rewrites the `parent::method()` statements that resolve into PHPUnit, which the converted chain + * no longer extends: without a parent PHP rejects `parent` at compile time, and on a converted base * the method is gone. A call reaching a method a local base declares stays, as does a call whose * result is used. An anonymous class inside the method has a parent of its own and is not entered. * - * A PHPUnit assertion is kept as an explicit `\PHPUnit\Framework\Assert::` call instead: the - * assertion rules convert the ones Testo maps, and the rest stay valid PHPUnit calls rather than - * a `parent::` that would stop the whole file from compiling. + * Only a call to a `TestCase` hook, or to the PHPUnit method the enclosing one overrides, is + * dropped. A PHPUnit assertion becomes an explicit `\PHPUnit\Framework\Assert::` call: the + * assertion rules convert the ones Testo maps, and the rest stay valid PHPUnit calls. Any other + * call, such as `markTestSkipped()` or `expectException()`, becomes `self::` or `$this->`, the + * spelling the skip and expectation rules convert by name; dropping it would silently change what + * the test checks. + * + * Without the base's reflection, as for a class extending `TestCase` directly while PHPUnit cannot + * be resolved, every call is taken to reach PHPUnit. * * @return bool Whether a call was changed. */ - private function removePhpunitParentCalls(Class_ $class, ClassMethod $method): bool + private function rewritePhpunitParentCalls(?ClassReflection $base, ClassMethod $method): bool { - $name = $class->namespacedName?->toString(); - if ($name === null || !$this->reflectionProvider->hasClass($name)) { - return false; - } - - $parents = $this->reflectionProvider->getClass($name)->getParents(); + $native = $base?->getNativeReflection(); $changed = false; - $this->traverseNodesWithCallable($method, function (Node $node) use ($parents, &$changed): ?int { + # Within its own override a rewritten call would reach the override again. + $dropped = [...self::DROPPED_HOOKS, $method->name->toLowerString()]; + $inStatic = $method->isStatic(); + $this->traverseNodesWithCallable($method, function (Node $node) use ($native, $dropped, $inStatic, &$changed): ?int { if ($node instanceof Class_) { return NodeVisitor::DONT_TRAVERSE_CHILDREN; } @@ -244,14 +287,17 @@ private function removePhpunitParentCalls(Class_ $class, ClassMethod $method): b } $called = $node->expr->name->toString(); - foreach ($parents as $parent) { - $native = $parent->getNativeReflection(); - if (!\str_starts_with($parent->getName(), 'PHPUnit\\') - && $native->hasMethod($called) - && !\str_starts_with($native->getMethod($called)->getDeclaringClass()->getName(), 'PHPUnit\\') - ) { + # The base's reflection covers every inherited method. A method no ancestor declares + # becomes `$this->` too: a visible call to a missing method rather than a statement that + # silently disappears. + $static = false; + if ($native?->hasMethod($called)) { + $declared = $native->getMethod($called); + if (!\str_starts_with($declared->getDeclaringClass()->getName(), 'PHPUnit\\')) { return null; } + + $static = $declared->isStatic(); } $changed = true; @@ -261,15 +307,26 @@ private function removePhpunitParentCalls(Class_ $class, ClassMethod $method): b return null; } - return NodeVisitor::REMOVE_NODE; + if (\in_array(\strtolower($called), $dropped, true)) { + return NodeVisitor::REMOVE_NODE; + } + + # A static method has no `$this` to call on. + if ($static || $inStatic) { + $node->expr->class = new Name('self'); + } else { + $node->expr = new MethodCall(new Variable('this'), $node->expr->name, $node->expr->args); + } + + return null; }); return $changed; } /** - * Only a static assertion declared on `Assert` survives the rewrite; `TestCase` hooks such as - * `assertPostConditions()` exist on the instance alone and are dropped with the other calls. + * Only a static assertion declared on `Assert` counts; `TestCase` hooks such as + * `assertPostConditions()` exist on the instance alone and are dropped as hooks. */ private function isPhpunitAssertion(StaticCall $call): bool { diff --git a/bridge/rector/src/PhpunitToTesto/ExtendsTestCaseToTestoRector/anonymous_class_parent_calls.php.inc b/bridge/rector/src/PhpunitToTesto/ExtendsTestCaseToTestoRector/anonymous_class_parent_calls.php.inc new file mode 100644 index 00000000..c24394b7 --- /dev/null +++ b/bridge/rector/src/PhpunitToTesto/ExtendsTestCaseToTestoRector/anonymous_class_parent_calls.php.inc @@ -0,0 +1,30 @@ +expectException(\RuntimeException::class); + $this->expectExceptionMessage('boom'); + throw new \RuntimeException('boom'); + } + + #[\Testo\Test] + public function testCounted(): void + { + $this->addToAssertionCount(1); + } +} diff --git a/bridge/rector/src/PhpunitToTesto/ExtendsTestCaseToTestoRector/parent_call_in_own_override_dropped.php.inc b/bridge/rector/src/PhpunitToTesto/ExtendsTestCaseToTestoRector/parent_call_in_own_override_dropped.php.inc new file mode 100644 index 00000000..78f8f646 --- /dev/null +++ b/bridge/rector/src/PhpunitToTesto/ExtendsTestCaseToTestoRector/parent_call_in_own_override_dropped.php.inc @@ -0,0 +1,18 @@ +` (instance), +so the skip and expectation rules convert it; one no rule maps stays a visible call to a missing method. Ownership is read from PHPStan's reflection of the class as loaded from source, so a class that `ExtendsTestCaseToTestoRector` detaches from `TestCase` in the same run still converts; that reflection is looked up by name, so it only counts when it comes from the same file. A class detached by an diff --git a/bridge/rector/tests/Stub/PhpunitAssertions.php b/bridge/rector/tests/Stub/PhpunitAssertions.php index fec08c2f..c0e25c88 100644 --- a/bridge/rector/tests/Stub/PhpunitAssertions.php +++ b/bridge/rector/tests/Stub/PhpunitAssertions.php @@ -208,12 +208,22 @@ abstract public static function assertThat($value, $constraint, $message = ''): abstract public static function assertTrue($condition, $message = ''): void; abstract public static function fail($message = ''): void; + + abstract public static function markTestIncomplete($message = ''): never; + + abstract public static function markTestSkipped($message = ''): never; } } if (!\class_exists(TestCase::class, false)) { abstract class TestCase extends Assert { + abstract public function addToAssertionCount($count): void; + + abstract public function expectException($exception): void; + + abstract public function expectExceptionMessage($message): void; + abstract protected function assertPreConditions(): void; abstract protected function assertPostConditions(): void; diff --git a/skills/testo-migrate-from-phpunit/references/migrate-with-rector.md b/skills/testo-migrate-from-phpunit/references/migrate-with-rector.md index 48f71cae..58c7610b 100644 --- a/skills/testo-migrate-from-phpunit/references/migrate-with-rector.md +++ b/skills/testo-migrate-from-phpunit/references/migrate-with-rector.md @@ -66,9 +66,13 @@ vendor/bin/rector process --config=rector-testo-migration.php (`git commit -am "migrate: mechanical Rector pass"`) so the structural pass has a clean base to diff against. > Rector detaches each class from `TestCase` and marks its test methods with `#[\Testo\Test]`, including -> subclasses of a project base class, and drops `parent::setUp();`-style statements that call into -> PHPUnit. A class on a PHPUnit base from `vendor/` (a framework's `TestCase`) is converted as well, but -> the class extending that base gets `#[\Testo\Skip]` naming it, since the base still runs on PHPUnit. +> subclasses of a project base class. Of its `parent::` statements that call into PHPUnit, a +> `parent::setUp();`-style hook call is dropped, as is a call inside an override of that same method +> (a wrapper around `expectException()` loses its delegation), and any other, such as +> `parent::markTestSkipped()`, becomes `self::`/`$this->` for the skip and expectation rules to +> convert. A class on a PHPUnit base from `vendor/` (a framework's `TestCase`) is converted as well, +> but the class extending that base gets `#[\Testo\Skip]` naming it, since the base still runs on +> PHPUnit. > Tests inherited from such a base are not converted. `scan-residuals.php` and the pitfalls in the > mapping cover them.