tests/phpunit/maintenance/MaintenanceBaseTestCase.php

   1 <?php
   2
   3 namespace MediaWiki\Tests\Maintenance;
   4
   5 use MediaWiki\Maintenance\Maintenance;
   6 use MediaWiki\Maintenance\MaintenanceFatalError;
   7 use MediaWikiIntegrationTestCase;
   8 use Wikimedia\TestingAccessWrapper;
   9
  10 abstract class MaintenanceBaseTestCase extends MediaWikiIntegrationTestCase {
  11
  12         /**
  13          * The main Maintenance instance that is used for testing, wrapped and mockable.
  14          *
  15          * @var Maintenance
  16          */
  17         protected $maintenance;
  18
  19         protected function setUp(): void {
  20                 parent::setUp();
  21
  22                 $this->maintenance = $this->createMaintenance();
  23         }
  24
  25         /**
  26          * Do a little stream cleanup to prevent output in case the child class
  27          * hasn't tested the capture buffer.
  28          */
  29         protected function tearDown(): void {
  30                 if ( $this->maintenance ) {
  31                         $this->maintenance->cleanupChanneled();
  32                 }
  33
  34                 // This is smelly, but maintenance scripts usually produce output, so
  35                 // we anticipate and ignore with a regex that will catch everything.
  36                 //
  37                 // If you call $this->expectOutputRegex in your subclass, this guard
  38                 // won't be triggered, and your specific pattern will be respected.
  39                 if ( !$this->hasExpectationOnOutput() ) {
  40                         $this->expectOutputRegex( '/.*/' );
  41                 }
  42
  43                 parent::tearDown();
  44         }
  45
  46         /**
  47          * Subclasses must implement this in order to use the $this->maintenance
  48          * variable.  Normally, it will be set like:
  49          *     return PopulateDatabaseMaintenance::class;
  50          *
  51          * If you need to change the way your maintenance class is constructed,
  52          * override createMaintenance.
  53          *
  54          * @return string Class name
  55          */
  56         abstract protected function getMaintenanceClass();
  57
  58         /**
  59          * Called by setUp to initialize $this->maintenance.
  60          *
  61          * @return Maintenance The Maintenance instance to test.
  62          */
  63         protected function createMaintenance() {
  64                 $className = $this->getMaintenanceClass();
  65                 $obj = new $className();
  66
  67                 // We use TestingAccessWrapper in order to access protected internals
  68                 // such as `output()`.
  69                 return TestingAccessWrapper::newFromObject( $obj );
  70         }
  71
  72         /**
  73          * Asserts the output before and after simulating shutdown
  74          *
  75          * This function simulates shutdown of self::maintenance.
  76          *
  77          * @param string $preShutdownOutput Expected output before simulating shutdown
  78          * @param bool $expectNLAppending Whether or not shutdown simulation is expected
  79          *   to add a newline to the output. If false, $preShutdownOutput is the
  80          *   expected output after shutdown simulation. Otherwise,
  81          *   $preShutdownOutput with an appended newline is the expected output
  82          *   after shutdown simulation.
  83          */
  84         protected function assertOutputPrePostShutdown( $preShutdownOutput, $expectNLAppending ) {
  85                 $this->assertEquals( $preShutdownOutput, $this->getActualOutput(),
  86                                 "Output before shutdown simulation" );
  87
  88                 $this->maintenance->cleanupChanneled();
  89
  90                 $postShutdownOutput = $preShutdownOutput . ( $expectNLAppending ? "\n" : "" );
  91                 $this->expectOutputString( $postShutdownOutput );
  92         }
  93
  94         /**
  95          * Expects that a call to Maintenance::fatalError occurs. When Maintenance::fatalError
  96          * is called, an exception is thrown which is marked as expected through this method.
  97          *
  98          * If you wish to assert on the error message provided to Maintenance::fatalError,
  99          * then use ::expectOutputString or ::expectOutputRegex.
 100          *
 101          * @param ?int $expectedCode The expected error code provided to Maintenance::fatalError
 102          * @since 1.43
 103          */
 104         protected function expectCallToFatalError( ?int $expectedCode = null ) {
 105                 $this->expectException( MaintenanceFatalError::class );
 106                 if ( $expectedCode !== null ) {
 107                         $this->expectExceptionCode( $expectedCode );
 108                 }
 109         }
 110
 111 }