tests/phpunit/maintenance/DumpAsserter.php

   1 <?php
   2
   3 namespace MediaWiki\Tests\Maintenance;
   4
   5 use PHPUnit\Framework\Assert;
   6 use XMLReader;
   7
   8 /**
   9  * Helper for asserting the structure of an XML dump stream.
  10  */
  11 class DumpAsserter {
  12
  13         /**
  14          * Holds the XMLReader used for analyzing an XML dump
  15          *
  16          * @var XMLReader|null
  17          */
  18         protected $xml = null;
  19
  20         /**
  21          * XML dump schema version
  22          *
  23          * @var string
  24          */
  25         protected $schemaVersion;
  26
  27         /**
  28          * DumpAsserts constructor.
  29          *
  30          * @param string $schemaVersion see XML_DUMP_SCHEMA_VERSION_XX
  31          */
  32         public function __construct( $schemaVersion ) {
  33                 $this->schemaVersion = $schemaVersion;
  34         }
  35
  36         /**
  37          * Step the current XML reader until node end of given name is found.
  38          *
  39          * @param string $name Name of the closing element to look for
  40          *   (e.g.: "mediawiki" when looking for </mediawiki>)
  41          *
  42          * @return bool True if the end node could be found. false otherwise.
  43          */
  44         public function skipToNodeEnd( $name ) {
  45                 while ( $this->xml->read() ) {
  46                         if ( $this->xml->nodeType == XMLReader::END_ELEMENT &&
  47                                 $this->xml->name == $name
  48                         ) {
  49                                 return true;
  50                         }
  51                 }
  52
  53                 return false;
  54         }
  55
  56         /**
  57          * Step the current XML reader to the first element start after the node
  58          * end of a given name.
  59          *
  60          * @param string $name Name of the closing element to look for
  61          *   (e.g.: "mediawiki" when looking for </mediawiki>)
  62          *
  63          * @return bool True if new element after the closing of $name could be
  64          *   found. false otherwise.
  65          */
  66         public function skipPastNodeEnd( $name ) {
  67                 Assert::assertTrue( $this->skipToNodeEnd( $name ),
  68                         "Skipping to end of $name" );
  69                 while ( $this->xml->read() ) {
  70                         if ( $this->xml->nodeType == XMLReader::ELEMENT ) {
  71                                 return true;
  72                         }
  73                 }
  74
  75                 return false;
  76         }
  77
  78         /**
  79          * Opens an XML file to analyze and optionally skips past siteinfo.
  80          *
  81          * @param string $fname Name of file to analyze
  82          * @param bool $skip_siteinfo (optional) If true, step the xml reader
  83          *   to the first element after </siteinfo>
  84          */
  85         public function assertDumpStart( $fname, $skip_siteinfo = true ) {
  86                 $this->xml = new XMLReader();
  87
  88                 Assert::assertTrue( $this->xml->open( $fname ),
  89                         "Opening temporary file $fname via XMLReader failed" );
  90                 if ( $skip_siteinfo ) {
  91                         Assert::assertTrue( $this->skipPastNodeEnd( "siteinfo" ),
  92                                 "Skipping past end of siteinfo" );
  93                 }
  94         }
  95
  96         /**
  97          * Asserts that the xml reader is at the final closing tag of an xml file and
  98          * closes the reader.
  99          *
 100          * @param string $name (optional) the name of the final tag
 101          *   (e.g.: "mediawiki" for </mediawiki>)
 102          */
 103         public function assertDumpEnd( $name = "mediawiki" ) {
 104                 $this->assertNodeEnd( $name, false );
 105                 if ( $this->xml->read() ) {
 106                         $this->skipWhitespace();
 107                 }
 108                 Assert::assertEquals( $this->xml->nodeType, XMLReader::NONE,
 109                         "No proper entity left to parse" );
 110                 $this->xml->close();
 111         }
 112
 113         /**
 114          * Steps the xml reader over white space
 115          */
 116         public function skipWhitespace() {
 117                 $cont = true;
 118                 while ( $cont && ( ( $this->xml->nodeType == XMLReader::WHITESPACE )
 119                         || ( $this->xml->nodeType == XMLReader::SIGNIFICANT_WHITESPACE ) ) ) {
 120                         $cont = $this->xml->read();
 121                 }
 122         }
 123
 124         /**
 125          * Asserts that the xml reader is at an element of given name, and optionally
 126          * skips past it.
 127          *
 128          * @param string $name The name of the element to check for
 129          *   (e.g.: "mediawiki" for <mediawiki>)
 130          * @param bool $skip (optional) if true, skip past the found element
 131          */
 132         public function assertNodeStart( $name, $skip = true ) {
 133                 Assert::assertEquals( $name, $this->xml->name, "Node name" );
 134                 Assert::assertEquals( XMLReader::ELEMENT, $this->xml->nodeType, "Node type" );
 135                 if ( $skip ) {
 136                         Assert::assertTrue( $this->xml->read(), "Skipping past start tag" );
 137                 }
 138         }
 139
 140         /**
 141          * Asserts that the xml reader is at an element of given name, and that element
 142          * is an empty tag.
 143          *
 144          * @param string $name The name of the element to check for
 145          *   (e.g.: "text" for <text/>)
 146          * @param bool $skip (optional) if true, skip past the found element
 147          * @param bool $skip_ws (optional) if true, also skip past white spaces that trail the
 148          *   closing element.
 149          */
 150         public function assertEmptyNode( $name, $skip = true, $skip_ws = true ) {
 151                 $this->assertNodeStart( $name, false );
 152                 Assert::assertFalse( $this->xml->hasValue, "$name tag has content" );
 153
 154                 if ( $skip ) {
 155                         Assert::assertTrue( $this->xml->read(), "Skipping $name tag" );
 156                         if ( ( $this->xml->nodeType == XMLReader::END_ELEMENT )
 157                                 && ( $this->xml->name == $name )
 158                         ) {
 159                                 $this->xml->read();
 160                         }
 161
 162                         if ( $skip_ws ) {
 163                                 $this->skipWhitespace();
 164                         }
 165                 }
 166         }
 167
 168         /**
 169          * Asserts that the xml reader is at an closing element of given name, and optionally
 170          * skips past it.
 171          *
 172          * @param string $name The name of the closing element to check for
 173          *   (e.g.: "mediawiki" for </mediawiki>)
 174          * @param bool $skip (optional) if true, skip past the found element
 175          */
 176         public function assertNodeEnd( $name, $skip = true ) {
 177                 Assert::assertEquals( $name, $this->xml->name, "Node name" );
 178                 Assert::assertEquals( XMLReader::END_ELEMENT, $this->xml->nodeType, "Node type" );
 179                 if ( $skip ) {
 180                         Assert::assertTrue( $this->xml->read(), "Skipping past end tag" );
 181                 }
 182         }
 183
 184         /**
 185          * Asserts that the xml reader is at an element of given tag that contains a given text,
 186          * and skips over the element.
 187          *
 188          * @param string $name The name of the element to check for
 189          *   (e.g.: "mediawiki" for <mediawiki>...</mediawiki>)
 190          * @param string|bool $text If string, check if it equals the elements text.
 191          *   If false, ignore the element's text
 192          * @param bool $skip_ws (optional) if true, skip past white spaces that trail the
 193          *   closing element.
 194          */
 195         public function assertTextNode( $name, $text, $skip_ws = true ) {
 196                 $this->assertNodeStart( $name );
 197
 198                 if ( $text !== false ) {
 199                         Assert::assertEquals( $text, $this->xml->value, "Text of node " . $name );
 200                 }
 201                 Assert::assertTrue( $this->xml->read(), "Skipping past processed text of " . $name );
 202                 $this->assertNodeEnd( $name );
 203
 204                 if ( $skip_ws ) {
 205                         $this->skipWhitespace();
 206                 }
 207         }
 208
 209         /**
 210          * Asserts that the xml reader is at the start of a page element and skips over the first
 211          * tags, after checking them.
 212          *
 213          * Besides the opening page element, this function also checks for and skips over the
 214          * title, ns, and id tags. Hence after this function, the xml reader is at the first
 215          * revision of the current page.
 216          *
 217          * @param int $id Id of the page to assert
 218          * @param int $ns Number of namespage to assert
 219          * @param string $name Title of the current page
 220          */
 221         public function assertPageStart( $id, $ns, $name ) {
 222                 $this->assertNodeStart( "page" );
 223                 $this->skipWhitespace();
 224
 225                 $this->assertTextNode( "title", $name );
 226                 $this->assertTextNode( "ns", $ns );
 227                 $this->assertTextNode( "id", $id );
 228         }
 229
 230         /**
 231          * Asserts that the xml reader is at the page's closing element and skips to the next
 232          * element.
 233          */
 234         public function assertPageEnd() {
 235                 $this->assertNodeEnd( "page" );
 236                 $this->skipWhitespace();
 237         }
 238
 239         /**
 240          * Asserts that the xml reader is at a revision and checks its representation before
 241          * skipping over it.
 242          *
 243          * @param int $id Id of the revision
 244          * @param string $summary Summary of the revision
 245          * @param int $text_id Id of the revision's text
 246          * @param int $text_bytes Number of bytes in the revision's text
 247          * @param string $text_sha1 The base36 SHA-1 of the revision's text
 248          * @param string|bool $text (optional) The revision's string, or false to check for a
 249          *            revision stub
 250          * @param int|bool $parentid (optional) id of the parent revision
 251          * @param string $model The expected content model id (default: CONTENT_MODEL_WIKITEXT)
 252          * @param string $format The expected format model id (default: CONTENT_FORMAT_WIKITEXT)
 253          */
 254         public function assertRevision( $id, $summary, $text_id, $text_bytes,
 255                 $text_sha1, $text = false, $parentid = false,
 256                 $model = CONTENT_MODEL_WIKITEXT, $format = CONTENT_FORMAT_WIKITEXT
 257         ) {
 258                 $this->assertNodeStart( "revision" );
 259                 $this->skipWhitespace();
 260
 261                 $this->assertTextNode( "id", $id );
 262                 if ( $parentid !== false ) {
 263                         $this->assertTextNode( "parentid", $parentid );
 264                 }
 265                 $this->assertTextNode( "timestamp", false );
 266
 267                 $this->assertNodeStart( "contributor" );
 268                 $this->skipWhitespace();
 269                 $this->assertTextNode( "username", false );
 270                 $this->assertTextNode( "id", false );
 271                 $this->assertNodeEnd( "contributor" );
 272                 $this->skipWhitespace();
 273
 274                 $this->assertTextNode( "comment", $summary );
 275                 $this->skipWhitespace();
 276
 277                 if ( $this->schemaVersion >= XML_DUMP_SCHEMA_VERSION_11 ) {
 278                         $this->assertTextNode( "origin", false );
 279                         $this->skipWhitespace();
 280                 }
 281
 282                 $this->assertTextNode( "model", $model );
 283                 $this->skipWhitespace();
 284
 285                 $this->assertTextNode( "format", $format );
 286                 $this->skipWhitespace();
 287
 288                 if ( $this->xml->name == "text" ) {
 289                         // note: <text> tag may occur here or at the very end.
 290                         $text_found = true;
 291                         $this->assertText( $id, $text_id, $text_bytes, $text );
 292                 } else {
 293                         $text_found = false;
 294                         if ( $this->schemaVersion >= XML_DUMP_SCHEMA_VERSION_11 ) {
 295                                 Assert::fail( 'Missing text node' );
 296                         }
 297                 }
 298
 299                 if ( $text_sha1 ) {
 300                         $this->assertTextNode( "sha1", $text_sha1 );
 301                 } else {
 302                         $this->assertEmptyNode( "sha1" );
 303                 }
 304
 305                 if ( !$text_found ) {
 306                         $this->assertText( $id, $text_id, $text_bytes, $text );
 307                 }
 308
 309                 $this->assertNodeEnd( "revision" );
 310                 $this->skipWhitespace();
 311         }
 312
 313         public function assertText( $id, $text_id, $text_bytes, $text ) {
 314                 $this->assertNodeStart( "text", false );
 315                 if ( $text_bytes !== false ) {
 316                         Assert::assertEquals( $this->xml->getAttribute( "bytes" ), $text_bytes,
 317                                 "Attribute 'bytes' of revision " . $id );
 318                 }
 319
 320                 if ( $text === false ) {
 321                         Assert::assertEquals( $this->xml->getAttribute( "id" ), $text_id,
 322                                 "Text id of revision " . $id );
 323                         $this->assertEmptyNode( "text" );
 324                 } else {
 325                         // Testing for a real dump
 326                         Assert::assertTrue( $this->xml->read(), "Skipping text start tag" );
 327                         Assert::assertEquals( $text, $this->xml->value, "Text of revision " . $id );
 328                         Assert::assertTrue( $this->xml->read(), "Skipping past text" );
 329                         $this->assertNodeEnd( "text" );
 330                         $this->skipWhitespace();
 331                 }
 332         }
 333
 334         /**
 335          * asserts that the xml reader is at the beginning of a log entry and skips over
 336          * it while analyzing it.
 337          *
 338          * @param int $id Id of the log entry
 339          * @param string $user_name User name of the log entry's performer
 340          * @param int $user_id User id of the log entry 's performer
 341          * @param string|null $comment Comment of the log entry. If null, the comment text is ignored.
 342          * @param string $type Type of the log entry
 343          * @param string $subtype Subtype of the log entry
 344          * @param string $title Title of the log entry's target
 345          * @param array $parameters (optional) unserialized data accompanying the log entry
 346          */
 347         public function assertLogItem( $id, $user_name, $user_id, $comment, $type,
 348                 $subtype, $title, $parameters = []
 349         ) {
 350                 $this->assertNodeStart( "logitem" );
 351                 $this->skipWhitespace();
 352
 353                 $this->assertTextNode( "id", $id );
 354                 $this->assertTextNode( "timestamp", false );
 355
 356                 $this->assertNodeStart( "contributor" );
 357                 $this->skipWhitespace();
 358                 $this->assertTextNode( "username", $user_name );
 359                 $this->assertTextNode( "id", $user_id );
 360                 $this->assertNodeEnd( "contributor" );
 361                 $this->skipWhitespace();
 362
 363                 if ( $comment !== null ) {
 364                         $this->assertTextNode( "comment", $comment );
 365                 }
 366                 $this->assertTextNode( "type", $type );
 367                 $this->assertTextNode( "action", $subtype );
 368                 $this->assertTextNode( "logtitle", $title );
 369
 370                 $this->assertNodeStart( "params" );
 371                 $parameters_xml = unserialize( $this->xml->value );
 372                 Assert::assertEquals( $parameters, $parameters_xml );
 373                 Assert::assertTrue( $this->xml->read(), "Skipping past processed text of params" );
 374                 $this->assertNodeEnd( "params" );
 375                 $this->skipWhitespace();
 376
 377                 $this->assertNodeEnd( "logitem" );
 378                 $this->skipWhitespace();
 379         }
 380 }