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 closing element of given name, and optionally
 142          * skips past it.
 143          *
 144          * @param string $name The name of the closing element to check for
 145          *   (e.g.: "mediawiki" for </mediawiki>)
 146          * @param bool $skip (optional) if true, skip past the found element
 147          */
 148         public function assertNodeEnd( $name, $skip = true ) {
 149                 Assert::assertEquals( $name, $this->xml->name, "Node name" );
 150                 Assert::assertEquals( XMLReader::END_ELEMENT, $this->xml->nodeType, "Node type" );
 151                 if ( $skip ) {
 152                         Assert::assertTrue( $this->xml->read(), "Skipping past end tag" );
 153                 }
 154         }
 155
 156         /**
 157          * Asserts that the xml reader is at an element of given tag that contains a given text,
 158          * and skips over the element.
 159          *
 160          * @param string $name The name of the element to check for
 161          *   (e.g.: "mediawiki" for <mediawiki>...</mediawiki>)
 162          * @param string|bool $text If string, check if it equals the elements text.
 163          *   If false, ignore the element's text
 164          * @param bool $skip_ws (optional) if true, skip past white spaces that trail the
 165          *   closing element.
 166          */
 167         public function assertTextNode( $name, $text, $skip_ws = true ) {
 168                 $this->assertNodeStart( $name );
 169
 170                 if ( $text !== false ) {
 171                         Assert::assertEquals( $text, $this->xml->value, "Text of node " . $name );
 172                 }
 173                 Assert::assertTrue( $this->xml->read(), "Skipping past processed text of " . $name );
 174                 $this->assertNodeEnd( $name );
 175
 176                 if ( $skip_ws ) {
 177                         $this->skipWhitespace();
 178                 }
 179         }
 180
 181         /**
 182          * Asserts that the xml reader is at the start of a page element and skips over the first
 183          * tags, after checking them.
 184          *
 185          * Besides the opening page element, this function also checks for and skips over the
 186          * title, ns, and id tags. Hence after this function, the xml reader is at the first
 187          * revision of the current page.
 188          *
 189          * @param int $id Id of the page to assert
 190          * @param int $ns Number of namespage to assert
 191          * @param string $name Title of the current page
 192          */
 193         public function assertPageStart( $id, $ns, $name ) {
 194                 $this->assertNodeStart( "page" );
 195                 $this->skipWhitespace();
 196
 197                 $this->assertTextNode( "title", $name );
 198                 $this->assertTextNode( "ns", $ns );
 199                 $this->assertTextNode( "id", $id );
 200         }
 201
 202         /**
 203          * Asserts that the xml reader is at the page's closing element and skips to the next
 204          * element.
 205          */
 206         public function assertPageEnd() {
 207                 $this->assertNodeEnd( "page" );
 208                 $this->skipWhitespace();
 209         }
 210
 211         /**
 212          * Asserts that the xml reader is at a revision and checks its representation before
 213          * skipping over it.
 214          *
 215          * @param int $id Id of the revision
 216          * @param string $summary Summary of the revision
 217          * @param int $text_id Id of the revision's text
 218          * @param int $text_bytes Number of bytes in the revision's text
 219          * @param string $text_sha1 The base36 SHA-1 of the revision's text
 220          * @param string|bool $text (optional) The revision's string, or false to check for a
 221          *            revision stub
 222          * @param int|bool $parentid (optional) id of the parent revision
 223          * @param string $model The expected content model id (default: CONTENT_MODEL_WIKITEXT)
 224          * @param string $format The expected format model id (default: CONTENT_FORMAT_WIKITEXT)
 225          */
 226         public function assertRevision( $id, $summary, $text_id, $text_bytes,
 227                 $text_sha1, $text = false, $parentid = false,
 228                 $model = CONTENT_MODEL_WIKITEXT, $format = CONTENT_FORMAT_WIKITEXT
 229         ) {
 230                 $this->assertNodeStart( "revision" );
 231                 $this->skipWhitespace();
 232
 233                 $this->assertTextNode( "id", $id );
 234                 if ( $parentid !== false ) {
 235                         $this->assertTextNode( "parentid", $parentid );
 236                 }
 237                 $this->assertTextNode( "timestamp", false );
 238
 239                 $this->assertNodeStart( "contributor" );
 240                 $this->skipWhitespace();
 241                 $this->assertTextNode( "ip", false );
 242                 $this->assertNodeEnd( "contributor" );
 243                 $this->skipWhitespace();
 244
 245                 $this->assertTextNode( "comment", $summary );
 246                 $this->skipWhitespace();
 247
 248                 $this->assertTextNode( "model", $model );
 249                 $this->skipWhitespace();
 250
 251                 $this->assertTextNode( "format", $format );
 252                 $this->skipWhitespace();
 253
 254                 if ( $this->xml->name == "text" ) {
 255                         // note: <text> tag may occur here or at the very end.
 256                         $text_found = true;
 257                         $this->assertText( $id, $text_id, $text_bytes, $text );
 258                 } else {
 259                         $text_found = false;
 260                 }
 261
 262                 $this->assertTextNode( "sha1", $text_sha1 );
 263
 264                 if ( !$text_found ) {
 265                         $this->assertText( $id, $text_id, $text_bytes, $text );
 266                 }
 267
 268                 $this->assertNodeEnd( "revision" );
 269                 $this->skipWhitespace();
 270         }
 271
 272         public function assertText( $id, $text_id, $text_bytes, $text ) {
 273                 $this->assertNodeStart( "text", false );
 274                 if ( $text_bytes !== false ) {
 275                         Assert::assertEquals( $this->xml->getAttribute( "bytes" ), $text_bytes,
 276                                 "Attribute 'bytes' of revision " . $id );
 277                 }
 278
 279                 if ( $text === false ) {
 280                         // Testing for a stub
 281                         Assert::assertEquals( $this->xml->getAttribute( "id" ), $text_id,
 282                                 "Text id of revision " . $id );
 283                         Assert::assertFalse( $this->xml->hasValue, "Revision has text" );
 284                         Assert::assertTrue( $this->xml->read(), "Skipping text start tag" );
 285                         if ( ( $this->xml->nodeType == XMLReader::END_ELEMENT )
 286                                 && ( $this->xml->name == "text" )
 287                         ) {
 288                                 $this->xml->read();
 289                         }
 290                         $this->skipWhitespace();
 291                 } else {
 292                         // Testing for a real dump
 293                         Assert::assertTrue( $this->xml->read(), "Skipping text start tag" );
 294                         Assert::assertEquals( $text, $this->xml->value, "Text of revision " . $id );
 295                         Assert::assertTrue( $this->xml->read(), "Skipping past text" );
 296                         $this->assertNodeEnd( "text" );
 297                         $this->skipWhitespace();
 298                 }
 299         }
 300
 301         /**
 302          * asserts that the xml reader is at the beginning of a log entry and skips over
 303          * it while analyzing it.
 304          *
 305          * @param int $id Id of the log entry
 306          * @param string $user_name User name of the log entry's performer
 307          * @param int $user_id User id of the log entry 's performer
 308          * @param string|null $comment Comment of the log entry. If null, the comment text is ignored.
 309          * @param string $type Type of the log entry
 310          * @param string $subtype Subtype of the log entry
 311          * @param string $title Title of the log entry's target
 312          * @param array $parameters (optional) unserialized data accompanying the log entry
 313          */
 314         public function assertLogItem( $id, $user_name, $user_id, $comment, $type,
 315                 $subtype, $title, $parameters = []
 316         ) {
 317                 $this->assertNodeStart( "logitem" );
 318                 $this->skipWhitespace();
 319
 320                 $this->assertTextNode( "id", $id );
 321                 $this->assertTextNode( "timestamp", false );
 322
 323                 $this->assertNodeStart( "contributor" );
 324                 $this->skipWhitespace();
 325                 $this->assertTextNode( "username", $user_name );
 326                 $this->assertTextNode( "id", $user_id );
 327                 $this->assertNodeEnd( "contributor" );
 328                 $this->skipWhitespace();
 329
 330                 if ( $comment !== null ) {
 331                         $this->assertTextNode( "comment", $comment );
 332                 }
 333                 $this->assertTextNode( "type", $type );
 334                 $this->assertTextNode( "action", $subtype );
 335                 $this->assertTextNode( "logtitle", $title );
 336
 337                 $this->assertNodeStart( "params" );
 338                 $parameters_xml = unserialize( $this->xml->value );
 339                 Assert::assertEquals( $parameters, $parameters_xml );
 340                 Assert::assertTrue( $this->xml->read(), "Skipping past processed text of params" );
 341                 $this->assertNodeEnd( "params" );
 342                 $this->skipWhitespace();
 343
 344                 $this->assertNodeEnd( "logitem" );
 345                 $this->skipWhitespace();
 346         }
 347 }