3 abstract class MediaWikiTestCase
extends PHPUnit_Framework_TestCase
{
6 public $runDisabled = false;
9 * @var Array of TestUser
17 protected $oldTablePrefix;
18 protected $useTemporaryTables = true;
19 protected $reuseDB = false;
20 protected $tablesUsed = array(); // tables with data
22 private static $dbSetup = false;
25 * Holds the paths of temporary files/directories created through getNewTempFile,
26 * and getNewTempDirectory
30 private $tmpfiles = array();
33 * Holds original values of MediaWiki configuration settings
34 * to be restored in tearDown().
35 * See also setMwGlobal().
38 private $mwGlobals = array();
41 * Table name prefixes. Oracle likes it shorter.
43 const DB_PREFIX
= 'unittest_';
44 const ORA_DB_PREFIX
= 'ut_';
46 protected $supportedDBs = array(
53 function __construct( $name = null, array $data = array(), $dataName = '' ) {
54 parent
::__construct( $name, $data, $dataName );
56 $this->backupGlobals
= false;
57 $this->backupStaticAttributes
= false;
60 function run( PHPUnit_Framework_TestResult
$result = NULL ) {
61 /* Some functions require some kind of caching, and will end up using the db,
62 * which we can't allow, as that would open a new connection for mysql.
63 * Replace with a HashBag. They would not be going to persist anyway.
65 ObjectCache
::$instances[CACHE_DB
] = new HashBagOStuff
;
67 if( $this->needsDB() ) {
70 $this->useTemporaryTables
= !$this->getCliArg( 'use-normal-tables' );
71 $this->reuseDB
= $this->getCliArg('reuse-db');
73 $this->db
= wfGetDB( DB_MASTER
);
75 $this->checkDbIsSupported();
77 $this->oldTablePrefix
= $wgDBprefix;
79 if( !self
::$dbSetup ) {
81 self
::$dbSetup = true;
84 $this->addCoreDBData();
87 parent
::run( $result );
91 parent
::run( $result );
96 * obtains a new temporary file name
98 * The obtained filename is enlisted to be removed upon tearDown
100 * @returns string: absolute name of the temporary file
102 protected function getNewTempFile() {
103 $fname = tempnam( wfTempDir(), 'MW_PHPUnit_' . get_class( $this ) . '_' );
104 $this->tmpfiles
[] = $fname;
109 * obtains a new temporary directory
111 * The obtained directory is enlisted to be removed (recursively with all its contained
112 * files) upon tearDown.
114 * @returns string: absolute name of the temporary directory
116 protected function getNewTempDirectory() {
117 // Starting of with a temporary /file/.
118 $fname = $this->getNewTempFile();
120 // Converting the temporary /file/ to a /directory/
122 // The following is not atomic, but at least we now have a single place,
123 // where temporary directory creation is bundled and can be improved
125 $this->assertTrue( wfMkdirParents( $fname ) );
130 * setUp and tearDown should (where significant)
131 * happen in reverse order.
133 protected function setUp() {
137 //@todo: global variables to restore for *every* test
147 // Cleaning up temporary files
148 foreach ( $this->tmpfiles
as $fname ) {
149 if ( is_file( $fname ) ||
( is_link( $fname ) ) ) {
151 } elseif ( is_dir( $fname ) ) {
152 wfRecursiveRemoveDir( $fname );
156 // Clean up open transactions
157 if ( $this->needsDB() && $this->db
) {
158 while( $this->db
->trxLevel() > 0 ) {
159 $this->db
->rollback();
164 protected function tearDown() {
165 // Cleaning up temporary files
166 foreach ( $this->tmpfiles
as $fname ) {
167 if ( is_file( $fname ) ||
( is_link( $fname ) ) ) {
169 } elseif ( is_dir( $fname ) ) {
170 wfRecursiveRemoveDir( $fname );
174 // Clean up open transactions
175 if ( $this->needsDB() && $this->db
) {
176 while( $this->db
->trxLevel() > 0 ) {
177 $this->db
->rollback();
181 // Restore mw globals
182 foreach ( $this->mwGlobals
as $key => $value ) {
183 $GLOBALS[$key] = $value;
185 $this->mwGlobals
= array();
191 * Individual test functions may override globals (either directly or through this
192 * setMwGlobals() function), however one must call this method at least once for
193 * each key within the setUp().
194 * That way the key is added to the array of globals that will be reset afterwards
195 * in the tearDown(). And, equally important, that way all other tests are executed
196 * with the same settings (instead of using the unreliable local settings for most
197 * tests and fix it only for some tests).
201 * protected function setUp() {
202 * $this->setMwGlobals( 'wgRestrictStuff', true );
205 * function testFoo() {}
207 * function testBar() {}
208 * $this->assertTrue( self::getX()->doStuff() );
210 * $this->setMwGlobals( 'wgRestrictStuff', false );
211 * $this->assertTrue( self::getX()->doStuff() );
214 * function testQuux() {}
217 * @param array|string $pairs Key to the global variable, or an array
218 * of key/value pairs.
219 * @param mixed $value Value to set the global to (ignored
220 * if an array is given as first argument).
222 protected function setMwGlobals( $pairs, $value = null ) {
223 if ( !is_array( $pairs ) ) {
225 $this->mwGlobals
[$key] = $GLOBALS[$key];
226 $GLOBALS[$key] = $value;
228 foreach ( $pairs as $key => $value ) {
229 $this->mwGlobals
[$key] = $GLOBALS[$key];
230 $GLOBALS[$key] = $value;
236 * Merges the given values into a MW global array variable.
237 * Useful for setting some entries in a configuration array, instead of
238 * setting the entire array.
240 * @param String $name The name of the global, as in wgFooBar
241 * @param Array $values The array containing the entries to set in that global
243 * @throws MWException if the designated global is not an array.
245 protected function mergeMwGlobalArrayValue( $name, $values ) {
246 if ( !isset( $GLOBALS[$name] ) ) {
249 if ( !is_array( $GLOBALS[$name] ) ) {
250 throw new MWException( "MW global $name is not an array." );
253 //NOTE: do not use array_merge, it screws up for numeric keys.
254 $merged = $GLOBALS[$name];
255 foreach ( $values as $k => $v ) {
260 $this->setMwGlobals( $name, $merged );
263 function dbPrefix() {
264 return $this->db
->getType() == 'oracle' ? self
::ORA_DB_PREFIX
: self
::DB_PREFIX
;
268 # if the test says it uses database tables, it needs the database
269 if ( $this->tablesUsed
) {
273 # if the test says it belongs to the Database group, it needs the database
274 $rc = new ReflectionClass( $this );
275 if ( preg_match( '/@group +Database/im', $rc->getDocComment() ) ) {
283 * Stub. If a test needs to add additional data to the database, it should
284 * implement this method and do so
286 function addDBData() {}
288 private function addCoreDBData() {
289 # disabled for performance
290 #$this->tablesUsed[] = 'page';
291 #$this->tablesUsed[] = 'revision';
293 if ( $this->db
->getType() == 'oracle' ) {
295 # Insert 0 user to prevent FK violations
297 $this->db
->insert( 'user', array(
299 'user_name' => 'Anonymous' ), __METHOD__
, array( 'IGNORE' ) );
301 # Insert 0 page to prevent FK violations
303 $this->db
->insert( 'page', array(
305 'page_namespace' => 0,
307 'page_restrictions' => NULL,
309 'page_is_redirect' => 0,
312 'page_touched' => $this->db
->timestamp(),
314 'page_len' => 0 ), __METHOD__
, array( 'IGNORE' ) );
318 User
::resetIdByNameCache();
321 $user = User
::newFromName( 'UTSysop' );
323 if ( $user->idForName() == 0 ) {
324 $user->addToDatabase();
325 $user->setPassword( 'UTSysopPassword' );
327 $user->addGroup( 'sysop' );
328 $user->addGroup( 'bureaucrat' );
329 $user->saveSettings();
333 //Make 1 page with 1 revision
334 $page = WikiPage
::factory( Title
::newFromText( 'UTPage' ) );
335 if ( !$page->getId() == 0 ) {
336 $page->doEditContent(
337 new WikitextContent( 'UTContent' ),
341 User
::newFromName( 'UTSysop' ) );
345 private function initDB() {
347 if ( $wgDBprefix === $this->dbPrefix() ) {
348 throw new MWException( 'Cannot run unit tests, the database prefix is already "unittest_"' );
351 $tablesCloned = $this->listTables();
352 $dbClone = new CloneDatabase( $this->db
, $tablesCloned, $this->dbPrefix() );
353 $dbClone->useTemporaryTables( $this->useTemporaryTables
);
355 if ( ( $this->db
->getType() == 'oracle' ||
!$this->useTemporaryTables
) && $this->reuseDB
) {
356 CloneDatabase
::changePrefix( $this->dbPrefix() );
360 $dbClone->cloneTableStructure();
363 if ( $this->db
->getType() == 'oracle' ) {
364 $this->db
->query( 'BEGIN FILL_WIKI_INFO; END;' );
369 * Empty all tables so they can be repopulated for tests
371 private function resetDB() {
373 if ( $this->db
->getType() == 'oracle' ) {
374 if ( $this->useTemporaryTables
) {
375 wfGetLB()->closeAll();
376 $this->db
= wfGetDB( DB_MASTER
);
378 foreach( $this->tablesUsed
as $tbl ) {
379 if( $tbl == 'interwiki') continue;
380 $this->db
->query( 'TRUNCATE TABLE '.$this->db
->tableName($tbl), __METHOD__
);
384 foreach( $this->tablesUsed
as $tbl ) {
385 if( $tbl == 'interwiki' ||
$tbl == 'user' ) continue;
386 $this->db
->delete( $tbl, '*', __METHOD__
);
392 function __call( $func, $args ) {
393 static $compatibility = array(
394 'assertInternalType' => 'assertType',
395 'assertNotInternalType' => 'assertNotType',
396 'assertInstanceOf' => 'assertType',
397 'assertEmpty' => 'assertEmpty2',
400 if ( method_exists( $this->suite
, $func ) ) {
401 return call_user_func_array( array( $this->suite
, $func ), $args);
402 } elseif ( isset( $compatibility[$func] ) ) {
403 return call_user_func_array( array( $this, $compatibility[$func] ), $args);
405 throw new MWException( "Called non-existant $func method on "
406 . get_class( $this ) );
410 private function assertEmpty2( $value, $msg ) {
411 return $this->assertTrue( $value == '', $msg );
414 static private function unprefixTable( $tableName ) {
416 return substr( $tableName, strlen( $wgDBprefix ) );
419 static private function isNotUnittest( $table ) {
420 return strpos( $table, 'unittest_' ) !== 0;
423 protected function listTables() {
426 $tables = $this->db
->listTables( $wgDBprefix, __METHOD__
);
427 $tables = array_map( array( __CLASS__
, 'unprefixTable' ), $tables );
429 // Don't duplicate test tables from the previous fataled run
430 $tables = array_filter( $tables, array( __CLASS__
, 'isNotUnittest' ) );
432 if ( $this->db
->getType() == 'sqlite' ) {
433 $tables = array_flip( $tables );
434 // these are subtables of searchindex and don't need to be duped/dropped separately
435 unset( $tables['searchindex_content'] );
436 unset( $tables['searchindex_segdir'] );
437 unset( $tables['searchindex_segments'] );
438 $tables = array_flip( $tables );
443 protected function checkDbIsSupported() {
444 if( !in_array( $this->db
->getType(), $this->supportedDBs
) ) {
445 throw new MWException( $this->db
->getType() . " is not currently supported for unit testing." );
449 public function getCliArg( $offset ) {
451 if( isset( MediaWikiPHPUnitCommand
::$additionalOptions[$offset] ) ) {
452 return MediaWikiPHPUnitCommand
::$additionalOptions[$offset];
457 public function setCliArg( $offset, $value ) {
459 MediaWikiPHPUnitCommand
::$additionalOptions[$offset] = $value;
464 * Don't throw a warning if $function is deprecated and called later
466 * @param $function String
469 function hideDeprecated( $function ) {
470 wfSuppressWarnings();
471 wfDeprecated( $function );
476 * Asserts that the given database query yields the rows given by $expectedRows.
477 * The expected rows should be given as indexed (not associative) arrays, with
478 * the values given in the order of the columns in the $fields parameter.
479 * Note that the rows are sorted by the columns given in $fields.
483 * @param $table String|Array the table(s) to query
484 * @param $fields String|Array the columns to include in the result (and to sort by)
485 * @param $condition String|Array "where" condition(s)
486 * @param $expectedRows Array - an array of arrays giving the expected rows.
488 * @throws MWException if this test cases's needsDB() method doesn't return true.
489 * Test cases can use "@group Database" to enable database test support,
490 * or list the tables under testing in $this->tablesUsed, or override the
493 protected function assertSelect( $table, $fields, $condition, array $expectedRows ) {
494 if ( !$this->needsDB() ) {
495 throw new MWException( 'When testing database state, the test cases\'s needDB()' .
496 ' method should return true. Use @group Database or $this->tablesUsed.');
499 $db = wfGetDB( DB_SLAVE
);
501 $res = $db->select( $table, $fields, $condition, wfGetCaller(), array( 'ORDER BY' => $fields ) );
502 $this->assertNotEmpty( $res, "query failed: " . $db->lastError() );
506 foreach ( $expectedRows as $expected ) {
507 $r = $res->fetchRow();
508 self
::stripStringKeys( $r );
511 $this->assertNotEmpty( $r, "row #$i missing" );
513 $this->assertEquals( $expected, $r, "row #$i mismatches" );
516 $r = $res->fetchRow();
517 self
::stripStringKeys( $r );
519 $this->assertFalse( $r, "found extra row (after #$i)" );
523 * Utility method taking an array of elements and wrapping
524 * each element in it's own array. Useful for data providers
525 * that only return a single argument.
529 * @param array $elements
533 protected function arrayWrap( array $elements ) {
535 function( $element ) {
536 return array( $element );
543 * Assert that two arrays are equal. By default this means that both arrays need to hold
544 * the same set of values. Using additional arguments, order and associated key can also
545 * be set as relevant.
549 * @param array $expected
550 * @param array $actual
551 * @param boolean $ordered If the order of the values should match
552 * @param boolean $named If the keys should match
554 protected function assertArrayEquals( array $expected, array $actual, $ordered = false, $named = false ) {
556 $this->objectAssociativeSort( $expected );
557 $this->objectAssociativeSort( $actual );
561 $expected = array_values( $expected );
562 $actual = array_values( $actual );
565 call_user_func_array(
566 array( $this, 'assertEquals' ),
567 array_merge( array( $expected, $actual ), array_slice( func_get_args(), 4 ) )
572 * Put each HTML element on its own line and then equals() the results
574 * Use for nicely formatting of PHPUnit diff output when comparing very
579 * @param String $expected HTML on oneline
580 * @param String $actual HTML on oneline
581 * @param String $msg Optional message
583 protected function assertHTMLEquals( $expected, $actual, $msg='' ) {
584 $expected = str_replace( '>', ">\n", $expected );
585 $actual = str_replace( '>', ">\n", $actual );
587 $this->assertEquals( $expected, $actual, $msg );
591 * Does an associative sort that works for objects.
595 * @param array $array
597 protected function objectAssociativeSort( array &$array ) {
601 return serialize( $a ) > serialize( $b ) ?
1 : -1;
607 * Utility function for eliminating all string keys from an array.
608 * Useful to turn a database result row as returned by fetchRow() into
609 * a pure indexed array.
613 * @param $r mixed the array to remove string keys from.
615 protected static function stripStringKeys( &$r ) {
616 if ( !is_array( $r ) ) {
620 foreach ( $r as $k => $v ) {
621 if ( is_string( $k ) ) {
628 * Asserts that the provided variable is of the specified
629 * internal type or equals the $value argument. This is useful
630 * for testing return types of functions that return a certain
631 * type or *value* when not set or on error.
635 * @param string $type
636 * @param mixed $actual
637 * @param mixed $value
638 * @param string $message
640 protected function assertTypeOrValue( $type, $actual, $value = false, $message = '' ) {
641 if ( $actual === $value ) {
642 $this->assertTrue( true, $message );
645 $this->assertType( $type, $actual, $message );
650 * Asserts the type of the provided value. This can be either
651 * in internal type such as boolean or integer, or a class or
652 * interface the value extends or implements.
656 * @param string $type
657 * @param mixed $actual
658 * @param string $message
660 protected function assertType( $type, $actual, $message = '' ) {
661 if ( class_exists( $type ) ||
interface_exists( $type ) ) {
662 $this->assertInstanceOf( $type, $actual, $message );
665 $this->assertInternalType( $type, $actual, $message );
670 * Returns true iff the given namespace defaults to Wikitext
671 * according to $wgNamespaceContentModels
673 * @param int $ns The namespace ID to check
678 protected function isWikitextNS( $ns ) {
679 global $wgNamespaceContentModels;
681 if ( isset( $wgNamespaceContentModels[$ns] ) ) {
682 return $wgNamespaceContentModels[$ns] === CONTENT_MODEL_WIKITEXT
;