mediawiki-extensions-Discus.../tests/phpunit/TestUtils.php

157 lines
4.2 KiB
PHP
Raw Normal View History

<?php
namespace MediaWiki\Extension\DiscussionTools\Tests;
use FormatJson;
use MediaWiki\Extension\DiscussionTools\CommentParser;
use MediaWiki\MediaWikiServices;
Don't refer directly to PHP `dom` extension classes; avoid nonstandard behavior These changes ensure that DiscussionTools is independent of DOM library choice, and will not break if/when Parsoid switches to an alternate (more standards-compliant) DOM library. We run `phan` against the Dodo standards-compliant DOM library, so this ends up flagging uses of non-standard PHP extensions to the DOM. These will be suppressed for now with a "Nonstandard DOM" comment that can be grepped for, since they will eventually will need to be rewritten or worked around. Most frequent issues: * Node::nodeValue and Node::textContent and Element::getAttribute() can return null in a spec-compliant implementation. Add `?? ''` to make spec-compliant results consistent w/ what PHP returns. * DOMXPath doesn't accept anything except DOMDocument. These uses should be replaced with DOMCompat::querySelectorAll() or similar (which end up using DOMXPath under the covers for DOMDocument any way, but are implemented more efficiently in a spec-compliant implementation). * A couple of times we have code like: `while ($node->firstChild!==null) { $node = $node->firstChild; }` and phan's analysis isn't strong enough to determine that $node is still non-null after the while. This same issue should appear with DOMDocument but phan doesn't complain for some reason. One apparently legit issue: * Node::insertBefore() is once called in a funny way which leans on the fact that the second option is optional in PHP. This seems to be a workaround for an ancient PHP bug, and can probably be safely removed. Bug: T287611 Bug: T217867 Change-Id: I3c4f41c3819770f85d68157c9f690d650b7266a3
2021-07-29 02:16:15 +00:00
use Wikimedia\Parsoid\DOM\Document;
use Wikimedia\Parsoid\DOM\Element;
use Wikimedia\Parsoid\Utils\DOMCompat;
use Wikimedia\Parsoid\Utils\DOMUtils;
trait TestUtils {
/**
* Create a Document from a string.
*
* @param string $html
Don't refer directly to PHP `dom` extension classes; avoid nonstandard behavior These changes ensure that DiscussionTools is independent of DOM library choice, and will not break if/when Parsoid switches to an alternate (more standards-compliant) DOM library. We run `phan` against the Dodo standards-compliant DOM library, so this ends up flagging uses of non-standard PHP extensions to the DOM. These will be suppressed for now with a "Nonstandard DOM" comment that can be grepped for, since they will eventually will need to be rewritten or worked around. Most frequent issues: * Node::nodeValue and Node::textContent and Element::getAttribute() can return null in a spec-compliant implementation. Add `?? ''` to make spec-compliant results consistent w/ what PHP returns. * DOMXPath doesn't accept anything except DOMDocument. These uses should be replaced with DOMCompat::querySelectorAll() or similar (which end up using DOMXPath under the covers for DOMDocument any way, but are implemented more efficiently in a spec-compliant implementation). * A couple of times we have code like: `while ($node->firstChild!==null) { $node = $node->firstChild; }` and phan's analysis isn't strong enough to determine that $node is still non-null after the while. This same issue should appear with DOMDocument but phan doesn't complain for some reason. One apparently legit issue: * Node::insertBefore() is once called in a funny way which leans on the fact that the second option is optional in PHP. This seems to be a workaround for an ancient PHP bug, and can probably be safely removed. Bug: T287611 Bug: T217867 Change-Id: I3c4f41c3819770f85d68157c9f690d650b7266a3
2021-07-29 02:16:15 +00:00
* @return Document
*/
Don't refer directly to PHP `dom` extension classes; avoid nonstandard behavior These changes ensure that DiscussionTools is independent of DOM library choice, and will not break if/when Parsoid switches to an alternate (more standards-compliant) DOM library. We run `phan` against the Dodo standards-compliant DOM library, so this ends up flagging uses of non-standard PHP extensions to the DOM. These will be suppressed for now with a "Nonstandard DOM" comment that can be grepped for, since they will eventually will need to be rewritten or worked around. Most frequent issues: * Node::nodeValue and Node::textContent and Element::getAttribute() can return null in a spec-compliant implementation. Add `?? ''` to make spec-compliant results consistent w/ what PHP returns. * DOMXPath doesn't accept anything except DOMDocument. These uses should be replaced with DOMCompat::querySelectorAll() or similar (which end up using DOMXPath under the covers for DOMDocument any way, but are implemented more efficiently in a spec-compliant implementation). * A couple of times we have code like: `while ($node->firstChild!==null) { $node = $node->firstChild; }` and phan's analysis isn't strong enough to determine that $node is still non-null after the while. This same issue should appear with DOMDocument but phan doesn't complain for some reason. One apparently legit issue: * Node::insertBefore() is once called in a funny way which leans on the fact that the second option is optional in PHP. This seems to be a workaround for an ancient PHP bug, and can probably be safely removed. Bug: T287611 Bug: T217867 Change-Id: I3c4f41c3819770f85d68157c9f690d650b7266a3
2021-07-29 02:16:15 +00:00
protected static function createDocument( string $html ): Document {
return DOMUtils::parseHTML( $html );
}
/**
* Return the node that is expected to contain thread items.
*
* @param Document $doc
* @return Element
*/
protected static function getThreadContainer( Document $doc ): Element {
// In tests created from Parsoid output, comments are contained directly in <body>.
// In tests created from old parser output, comments are contained in <div class="mw-parser-output">.
$body = DOMCompat::getBody( $doc );
$wrapper = DOMCompat::querySelector( $body, 'div.mw-parser-output' );
return $wrapper ?: $body;
}
/**
* Get text from path
*
* @param string $relativePath
* @return string
*/
protected static function getText( string $relativePath ): string {
return file_get_contents( __DIR__ . '/../' . $relativePath );
}
/**
* Write text to path
*
* @param string $relativePath
* @param string $text
*/
protected static function overwriteTextFile( string $relativePath, string $text ): void {
file_put_contents( __DIR__ . '/../' . $relativePath, $text );
}
/**
* Get parsed JSON from path
*
* @param string $relativePath
* @param bool $assoc See json_decode()
* @return array
*/
protected static function getJson( string $relativePath, bool $assoc = true ): array {
$json = json_decode(
file_get_contents( __DIR__ . '/' . $relativePath ),
$assoc
);
return $json;
}
/**
* Write JSON to path
*
* @param string $relativePath
* @param array $data
*/
protected static function overwriteJsonFile( string $relativePath, array $data ): void {
$json = FormatJson::encode( $data, "\t", FormatJson::ALL_OK );
file_put_contents( __DIR__ . '/' . $relativePath, $json . "\n" );
}
/**
* Get HTML from path
*
* @param string $relativePath
* @return string
*/
protected static function getHtml( string $relativePath ): string {
return file_get_contents( __DIR__ . '/../' . $relativePath );
}
/**
* Write HTML to path
*
* @param string $relPath
* @param Element $container
* @param string $origRelPath
*/
protected static function overwriteHtmlFile( string $relPath, Element $container, string $origRelPath ): void {
// Do not use $doc->saveHtml(), it outputs an awful soup of HTML entities for documents with
// non-ASCII characters
$html = file_get_contents( __DIR__ . '/../' . $origRelPath );
$newInnerHtml = DOMCompat::getInnerHTML( $container );
if ( strtolower( $container->tagName ) === 'body' ) {
// Apparently <body> innerHTML always has a trailing newline, even if the source HTML did not,
// and we need to preserve whatever whitespace was there to avoid test failures
preg_match( '`(\s*)(</body>|\z)`s', $html, $matches );
$newInnerHtml = rtrim( $newInnerHtml ) . $matches[1];
}
// Quote \ and $ in the replacement text
$quotedNewInnerHtml = strtr( $newInnerHtml, [ '\\' => '\\\\', '$' => '\\$' ] );
if ( strtolower( $container->tagName ) === 'body' ) {
if ( str_contains( $html, '<body' ) ) {
$html = preg_replace(
'`(<body[^>]*>)(.*)(</body>)`s',
'$1' . $quotedNewInnerHtml . '$3',
$html
);
} else {
$html = $newInnerHtml;
}
} else {
$html = preg_replace(
'`(<div class="mw-parser-output">)(.*)(</div>)`s',
'$1' . $quotedNewInnerHtml . '$3',
$html
);
}
file_put_contents( __DIR__ . '/../' . $relPath, $html );
}
/**
* Create a comment parser
*
* @param array $data
* @return CommentParser
*/
Change CommentParser into a service Goal: ----- To have a method like CommentParser::parse(), which just takes a node to parse and a title and returns plain data, so that we don't need to keep track of the config to construct a CommentParser object (the required config like content language is provided by services) and we don't need to keep that object around after parsing. Changes: -------- CommentParser.php: * …is now a service. Constructor only takes services as arguments. The node and title are passed to a new parse() method. * parse() should return plain data, but I split this part to a separate patch for ease of review: I49bfe019aa460651447fd383f73eafa9d7180a92. * CommentParser still cheats and accesses global state in a few places, e.g. calling Title::makeTitleSafe or CommentUtils::getTitleFromUrl, so we can't turn its tests into true unit tests. This work is left for future commits. LanguageData.php: * …is now a service, instead of a static class. Parser.js: * …is not a real service, but it's changed to behave in a similar way. Constructor takes only the required config as argument, and node and title are instead passed to a new parse() method. CommentParserTest.php: parser.test.js: * Can be simplified, now that we don't need a useless node and title to test internal methods that don't use them. testUtils.js: * Can be simplified, now that we don't need to override internal ResourceLoader stuff just to change the parser config. Change-Id: Iadb7757debe000025e52770ca51ebcf24ca8ee66
2022-02-19 02:43:21 +00:00
public static function createParser( array $data ): CommentParser {
$services = MediaWikiServices::getInstance();
return new CommentParser(
$services->getMainConfig(),
$services->getContentLanguage(),
$services->getLanguageConverterFactory(),
new MockLanguageData( $data ),
$services->getTitleParser()
);
}
}