Introduce TestRunAwareTestListener

[rpkamp]

Adds startTestRun and endTestRun hooks to TestListener so implementing
classes don't have to check whether a startTestSuite call is the first
one, plus it allows implementers to do something after the very last
test, which is usefull for implementers that want to buffer data and
only output once everything is done.

[codecov]

Codecov Report

Merging #3381 into master will increase coverage by 0.01%.
The diff coverage is 96.96%.

@@             Coverage Diff              @@
##             master    #3381      +/-   ##
============================================
+ Coverage     82.95%   82.97%   +0.01%     
- Complexity     3569     3580      +11     
============================================
  Files           143      143              
  Lines          9499     9513      +14     
============================================
+ Hits           7880     7893      +13     
- Misses         1619     1620       +1

Impacted Files	Coverage Δ	Complexity Δ
src/Runner/Hook/TestListenerAdapter.php	100% <100%> (ø)	34 <6> (+6)	⬆️
src/Framework/TestResult.php	75.97% <100%> (+0.47%)	173 <6> (+5)	⬆️
src/TextUI/TestRunner.php	68.46% <100%> (-0.3%)	284 <0> (-2)
src/TextUI/ResultPrinter.php	97.35% <100%> (+0.02%)	80 <2> (+1)	⬆️
src/Util/Log/TeamCity.php	52.76% <85.71%> (-0.04%)	63 <2> (+1)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bcbb5e0...f226210. Read the comment docs.

[sebastianbergmann]

BeforeFirstTestHook and AfterLastTestHook already exist. Or am I missing something?

[sebastianbergmann]

Maybe I should have documented the fact that the legacy TestListener interface that contains way too many methods will eventually go away.

Units of code that want to observe test execution should use the new TestHook interfaces. This is done by writing a class that implements one or more TestHook interfaces and registering it as a test runner extension.

[rpkamp]

Okay, so basically I've made the lagacy code forward compatible? 😄

Okay, if the TestListener needs to go -which I agree would be a good thing, as it doesn't really adhere to the Interface Seggregation Principle- then what happens to the printers?

The printers are currently all implemented as TestListeners, but should they become extensions instead?

The whole point of this PR was to get a signal in the CliTestDoxPrinter when the last test had run so we could output any buffered content, required for #3380; my idea was to create a BufferedTestListener as a decorator for other TestListeners that would order and output all data at the end when all test are done. This decorator could then be used general purposes for all kinds of printers that need sorted output.

Also, I don't like using printResults as a signal to output the buffered content, as printResult is not part of any interface, so it relies on duck typing.

The interfaces exist, now it's a matter of figuring out how to best use them to solve this, I think.

[epdenouden]

@rpkamp Perhaps the caching listener (or listening cache? :) can be of some inspiration too:

phpunit/src/Runner/ResultCacheExtension.php

Line 12 in 1349e75

final class ResultCacheExtension implements AfterSuccessfulTestHook, AfterSkippedTestHook, AfterRiskyTestHook, AfterIncompleteTestHook, AfterTestErrorHook, AfterTestWarningHook, AfterTestFailureHook, AfterLastTestHook

It started off as a version of the old listener-printer structure, then @sebastianbergmann asked to refactor it more cleanly before merge. Works like a charm.

[rpkamp]

@epdenouden yes, that looks good.

However, since that's an extension and the printer is a TestListener I'd need an adapter. I'd like a decorator instead, but for that to work the printer would need to be an extension too 🙂