Parser tests
bin/parserTests.php
in Parsoid's repository).Most commonly, parser test case specifies wikitext (commonly input) and HTML (commonly output), to confirm that things operate as expected. The actual output is compared with the desired result, and thus, the parser test cases (also known as parser tests) can be helpful at spotting regressions.
The parser test cases reside in the tests/parser/
directory. Extensions should place their tests in a tests/parser/
directory.
They can be run both through the phpunit test suite as well as the standalone parserTests.php script. So, a parser test failure will trigger a Jenkins test failure.
Syntax & execution[edit]
Version 2 format[edit]
- Starting with 1.35, parser tests are required to be in the Version 2 format. Specifying version 2 indicates that the tests are ready to be run in "tidy" mode (See T249138).
- To indicate your parser tests are run in version 2 format, the first line in your parser test file must be
!! Version 2
Enabling hooks[edit]
In order to be sure that the extension tag tag1
is loaded add at the beginning of the file:
!! hooks
tag1
!! endhooks
Adding articles[edit]
In order to create a new article, the syntax is:
!! article
Template:Simple template
!! text
A ''simple'' template.
!! endarticle
Layout of a parser test[edit]
Besides the test time, a test has a number of sections: options
(optional), config
(optional), wikitext
, wikitext/edited
(optional), html
(optional), html/php
(optional), html/parsoid
(optional), html/parsoid+standalone
(optional).
The wikitext/edited
and the various html/parsoid*
sections are only relevant when running a test with Parsoid. Parsoid also allows additional configuration with additional test-specific options in the options section.
Syntax is as follows for a simple test.
!! Version 2
!! test
Simple paragraph
!! config
wgRestrictDisplayTitle=false
!! wikitext
This is a simple paragraph.
!! html
<p>This is a simple paragraph.
</p>
!! end
Configuration section[edit]
If you specify configuration settings there, make sure you don't have any whitespace between your expressions, as whitespace isn't trimmed by the test runner.
Options section[edit]
Each option should come on its own line.
disabled
disables the test.php
runs the test only with the core's default parser unless Parsoid-specific HTML sections are present. The "php" name is a historical remnant from when Parsoid was a Node.js codebase.parsoid=comma-separated-modes
orparsoid={...}
(JSON format object) enable Parsoid-specific options.- Ex:
parsoid=wt2html,wt2wt
runs this test in only those 2 modes. By default, the test is run all available test modes for the test given the wikitext and html sections. In the common case, this defaults to running the test in wt2html, wt2wt, html2wt, html2html, and selser modes. The selser mode is an abbreviation for a test mode where the HTML section is edited in a number of automated ways which is then converted to wikitext using Parsoid's selective-serialization (selser henceforth) transformations. TODO: Add a link to a wikipage that explains Parsoid's various transformations. - In the JSON format object, the following keys are current recognized
modes, selser, changes, suppressErrors, normalizePhp,
modes
: This is a comma separated list of Parsoid modes to runselser
: If selser is one of the test modes in the modes property, this property can optionally specify"noauto"
to indicate automatic edits for this test should not be generated. If so, only manual edits as specified by thechanges
property will be applied.changes
: This format is described separately below. This option will need to be paired with awikitext/edited
section in the test (see below) that specifies the expected wikitext output when this edited HTML is converted (via selser) to wikitext by Parsoid.
- Ex:
changes format
This is an array of individual changes to apply to the DOM of the HTML generated by transforming wikitext. Each element of the array contains 3 or more elements: (a) jquery selector to select a DOM node (b) the type of change to apply to the selected node (c) the relevant values / content needed to apply the change specified.
More succinctly, each array element represents a jquery method call. So, [x,y,z...] becomes $(x)[y](z....)
So, ['fig', 'attr', 'width', '120'] is interpreted as $('fig').attr('width', '120')
Right now, the following jquery methods are recognized: after, addClass, append, attr, before, empty, html, remove, removeAttr, removeClass, text, wrap
See http://api.jquery.com/ for documentation of these methods.
"contents" as second argument calls the jquery .contents() method on the results of the selector in the first argument, which is a good way to get at the text and comment nodes.
Wikitext sections[edit]
wikitext
section: This is expected to be present in all tests is the that specifies the wikitext to be processed to HTML (or in Parsoid html2wt and wt2wt test modes, the wikitext to generate from the HTML sections).wikitext/edited
section: This section is only relevant in Parsoid test runs. For tests that provide a manual set of changes to apply to the HTML generated from the wikitext section, this is the output expected when Parsoid converts that edited HTML back to wikitext.
HTML sections[edit]
TODO
Extension.json & parser tests[edit]
Extensions that place their tests in tests/parser/
and are using extension.json will automatically have their parser tests run. For extensions using the legacy extension loading system, they can use:
$wgParserTestFiles[] = __DIR__ . "/myParserTests.txt";
Running tests with parserTests.php[edit]
To run the parser tests, go to the root directory of your local MediaWiki installation and execute the following from the command line:
php tests/parser/parserTests.php
tests/parserTests.php
.To run tests for just one file, use --file=...
param.
See more params with --help
.
php tests/parser/parserTests.php --file=extensions/Kartographer/tests/parser/parserTests.txt
Parsoid-specific test runner options[edit]
These options aren't available with MediaWiki core's paresr test runner in MW 1.38 and prior. You can run tests in Parsoid mode via the --parsoid
option. The best and most up-to-date documentation of all available options is to run
php tests/parser/parserTests.php --help
Setting global config variables[edit]
To set default global variables for all parser tests in an extension, use the ParserTestGlobals hook.
In a specific test, set the config variables as follows:
!! test
Your Test Name
!! config
wgVariableName=true
!! wikitext
...