Skip to content

Latest commit

 

History

History
174 lines (134 loc) · 7.76 KB

UPGRADE.md

File metadata and controls

174 lines (134 loc) · 7.76 KB

Upgrading to the PHPUnit engine

Asynit no longer has a runner of its own. bin/asynit boots PHPUnit, so the CLI, the configuration file, the output, the loggers and the exit codes are PHPUnit's. What is left of asynit is what PHPUnit cannot do: run tests concurrently, and order them with a #[Depend] graph that can point at any method of any class.

Most of the migration is mechanical and is done by the Rector set shipped with asynit. The rest is listed under What Rector will not do.

Run the Rector set

composer require --dev rector/rector
<?php
// rector.php
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([__DIR__.'/tests'])
    // keeps the diff readable: imports the classes it introduces and drops the ones it orphans
    ->withImportNames(importShortClasses: false, removeUnusedImports: true)
    ->withSets([__DIR__.'/vendor/jolicode/asynit/config/rector/asynit-phpunit.php']);
vendor/bin/rector process
vendor/bin/rector process

Run it twice. The first pass makes your classes extend PHPUnit\Framework\TestCase; the assertion renames only match once that is true, so they land on the second pass.

Assertions called from a trait are not rewritten. The renames only apply to calls Rector can tell are made on a TestCase, and inside a trait $this could be anything. Grep your traits for the assertions listed below and fix them by hand.

Warning

If PHP CS Fixer runs on your tests with @Symfony or @PhpCsFixer, disable php_unit_method_casing before its next run: once your classes extend TestCase, it renames test_foo() to testFoo() and silently breaks every #[Depend('test_foo')]. See below.

What it changes

Before After
#[Asynit\Attribute\TestCase] on the class extends PHPUnit\Framework\TestCase
use Asynit\Assert\AssertCaseTrait; removed, PHPUnit's TestCase carries the assertions
#[Asynit\Attribute\Test] #[PHPUnit\Framework\Attributes\Test]
#[Asynit\Attribute\DisplayName('...')] #[PHPUnit\Framework\Attributes\TestDox('...')]
#[OnCreate] public function boot(HttpClientConfiguration $c) #[Before] public function boot()
assertRegExp / assertNotRegExp assertMatchesRegularExpression / assertDoesNotMatchRegularExpression
assertFileNotExists assertFileDoesNotExist
assertInternalType('int', $v) assertIsInt($v), and the rest of the assertIs* family
assertNotInternalType('int', $v) assertIsNotInt($v)
assertContains($needle, $haystack) on a string assertStringContainsString($needle, $haystack), only when $haystack is known to be a string
assertEquals($e, $a, $message, $delta) assertEqualsWithDelta($e, $a, $delta, $message)

#[Depend], #[HttpClientConfiguration], the HTTP client traits ($this->get(), $this->post(), …) and assertStatusCode / assertContentType / assertHtml are unchanged.

PHPUnit's own #[Depends] and #[DependsExternal] work too, and are ordered by the same graph, so you can mix them or move to them over time. #[DependsOnClass] is not supported.

A class that already extends something is left alone rather than having its parent rewritten — make it extend PHPUnit\Framework\TestCase yourself, or have its own base class do so.

What Rector will not do

Test discovery: file and class names

Asynit found tests through #[TestCase]; PHPUnit finds them by file name. By default it only looks at *Test.php, and the class has to match the file name.

Rather than rename every file, widen the suffix in phpunit.xml:

<testsuites>
    <testsuite name="asynit">
        <directory suffix=".php">tests</directory>
    </testsuite>
</testsuites>

A method is a test if it is named test* or carries #[Test] — the same rule asynit used, so nothing to do there.

The command line

Asynit's options are gone. The ones that describe the run rather than a test case are environment variables now, because PHPUnit's CLI is not asynit's to extend.

Before After
bin/asynit tests bin/asynit (paths come from phpunit.xml)
--concurrency 5 ASYNIT_CONCURRENCY=5
--host https://api.example.com ASYNIT_HOST=https://api.example.com
--timeout 30 ASYNIT_TIMEOUT=30
--retry 2 ASYNIT_RETRY=2
--allow-self-signed-certificate ASYNIT_ALLOW_SELF_SIGNED_CERTIFICATE=1
--report report.xml --log-junit report.xml
--filter foo --filter foo (PHPUnit's, regex over Class::method)
--bootstrap file.php --bootstrap file.php (or bootstrap= in phpunit.xml)
--order no equivalent; asynit always orders by the dependency graph

Assertions with no direct equivalent

These came from asynit's bovigo-backed trait and have to be rewritten by hand:

Before Do this instead
assertContains($needle, $haystack) assertStringContainsString for strings, assertContains for arrays — the old one accepted both, so Rector only rewrites it when it can tell $haystack is a string
assertNotContains($needle, $haystack) assertStringNotContainsString or assertNotContains, same reason
assertInternalType($type, $v) Rector handles a literal $type; a variable one has to be turned into the matching assertIs*() by hand
assertNotEquals($e, $a, $message, $delta) assertNotEqualsWithDelta($e, $a, $delta, $message)
assertContainsSubset($array, $subset) no PHPUnit equivalent, see below
$this->assert($value, $predicate, $description) the bovigo escape hatch is gone; use the matching PHPUnit assertion

assertContains is the one worth grepping for first: it is common, and whatever Rector left behind needs a look.

assertContainsSubset() checked that $subset was contained in $array, recursively and by loose comparison (its $strict argument was ignored). If you use it a lot, rather than rewriting every call, put it back on your own base class or in a trait:

public static function assertContainsSubset(array $array, array $subset, bool $strict = false, string $message = ''): void
{
    self::assertEquals($array, array_replace_recursive($array, $subset), $message);
}

It behaves as it did, and a failure now shows a diff of what differs.

Tests that assert nothing

PHPUnit reports a test that performs no assertion as risky. Asynit did not. A test that only exists to produce a value for its dependents is not flagged — asynit knows it is a producer — but a method named test* that asserts nothing is. Expect a few to surface: a test that only sends a request, or only waits, used to pass silently. Either assert something or mark it:

#[\PHPUnit\Framework\Attributes\DoesNotPerformAssertions]
public function testProducesAToken(): string
{
    return 'token';
}

PHP CS Fixer renames snake_case tests

Once your classes extend PHPUnit\Framework\TestCase, the @Symfony and @PhpCsFixer rule sets turn on php_unit_method_casing, which renames test_foo() to testFoo(). Nothing updates the strings that point at those methods, so every #[Depend('test_foo')] breaks, and so does anything else relying on the method name. Turn the rule off before running the fixer on the migrated suite:

// .php-cs-fixer.php
return (new PhpCsFixer\Config())
    ->setRules([
        '@Symfony' => true,
        'php_unit_method_casing' => false,
    ]);

Things that are simply gone

  • Code coverage is not collected: PHPUnit drives it through a per-test singleton that concurrency breaks.
  • PHPUnit's deprecation and notice reporting is not produced, for the same reason. PHP errors still fail the test, as they did under asynit.

ARCHITECTURE.md explains why for each of these.