Document how to integrate with PHPUnit

[greg0ire]

Right now, it is possible to display Doctrine deprecations with a bit of PHPUnit configuration.
Note that this does not seem to clash with triggering self-deprecations, provided you use the VerifyDeprecations trait in tests that call the deprecated pieces of code.

[greg0ire]

Stolen from @wouterj at phpDocumentor/guides#1184

[wouterj]

Note that this does not seem to clash with triggering self-deprecations, provided you use the VerifyDeprecations trait in tests that call the deprecated pieces of code.

This is not 100% true, you must use PHPUnit's WithoutErrorHandler in tests that expect deprecations. This will disable the entire error handler (so warnings/errors also won't be reported for that specific test), which is a bit of a drawback.

[greg0ire]

you must use PHPUnit's WithoutErrorHandler in tests that expect deprecations

Why do you have to do that, and how do you do that? I tried using just VerifyDeprecations on a test case that triggered some, and it did not seem to have any wrong side effects 🤔

[wouterj]

Using failOnDeprecation="true" you tell phpunit that a deprecation notice should be regarded as a test failure (i.e. exit code != 0).

Without #[WithoutErrorHandler], the deprecation is caught by PHPUnit's error handler which marks the test run as failed (Deprecation::enableTrackingDeprecations() does not disable the trigger mode set by the env var).

[greg0ire]

@wouterj that's not what I observe.

Without use VerifyDeprecations

$ vendor/bin/phpunit
PHPUnit 11.4.4 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.14
Configuration: /home/greg/dev/DoctrineFixturesBundle/phpunit.xml.dist

D..............                                                   15 / 15 (100%)

Time: 00:00.088, Memory: 16.00 MB

1 test triggered 1 deprecation:

1) /home/greg/dev/DoctrineFixturesBundle/vendor/doctrine/deprecations/lib/Doctrine/Deprecations/Deprecation.php:210
pwet (SymfonyFixturesLoader.php:36 called by getTest_Doctrine_Fixtures_LoaderService.php:23, pwet, package doctrine/orm)

Triggered by:

* Doctrine\Bundle\FixturesBundle\Tests\IntegrationTest::testFixturesLoader
  /home/greg/dev/DoctrineFixturesBundle/tests/IntegrationTest.php:33

OK, but there were issues!
Tests: 15, Assertions: 46, Deprecations: 1.
╭─~/dev/DoctrineFixturesBundle on be1bc35 ✘
╰$ echo $?
1

With use VerifyDeprecations

$ vendor/bin/phpunit
PHPUnit 11.4.4 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.14
Configuration: /home/greg/dev/DoctrineFixturesBundle/phpunit.xml.dist

...............                                                   15 / 15 (100%)

Time: 00:00.087, Memory: 14.00 MB

OK, but there were issues!
Tests: 15, Assertions: 46, PHPUnit Deprecations: 2.
╭─~/dev/DoctrineFixturesBundle on be1bc35 ✘
╰$ echo $?
0

Deprecation::enableTrackingDeprecations() does not disable the trigger mode set by the env var

Ah I think I found a bug. It all depends whether you call it before calling trigger(), because trigger() starts like this:

deprecations/src/Deprecation.php

Line 80 in 0d0c25d

$type = self::$type ?? self::getTypeFromEnv();

So I think you're right about the necessity to add #[WithoutErrorHandler], but that's not all, you also have to somehow make sure the env is read into Deprecations::$type before using VerifyDeprecations, otherwise you will mask all subsequent calls to trigger.

[greg0ire]

I pushed a code change that I believe addresses the issue