Příručka:Parsovací testy

From mediawiki.org
This page is a translated version of the page Manual:Parser tests and the translation is 21% complete.
Části specifické pro Parsoid a možnosti specifické pro Parsoid jsou relevantní pouze pro (a) testovací soubory analyzátoru v úložišti Parsoid, (b) testovací soubory analyzátoru, které byly označeny jako kompatibilní s Parsoidem. Všimněte si také, že MW 1.38 a starší nepodporují spouštění testů Parsoid prostřednictvím testovacího programu parserTests.php v jádře MediaWiki. Tyto možnosti jsou však dostupné v testovacím programu Parsoid (bin/parserTests.php v úložišti Parsoid).

Testovací případ analyzátoru nejčastěji specifikuje wikitext (běžný vstup) a HTML (běžný výstup), aby se potvrdilo, že věci fungují podle očekávání. Skutečný výstup je porovnán s požadovaným výsledkem, a proto testovací případy analyzátoru (také známé jako testy analyzátoru) mohou být užitečné při zjišťování regresí.

Testovací případy analyzátoru jsou umístěny v adresáři tests/parser/. Rozšíření by měla umístit své testy do adresáře tests/parser/.

Mohou být spuštěny jak prostřednictvím testovací sady phpunit, tak pomocí samostatného skriptu parserTests.php. Selhání testu analyzátoru tedy vyvolá selhání Jenkinsova testu.

Syntaxe a provedení

Formát verze 2

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, you can use the options section at the top of the file (see below).

!! options
version=2
!! end

Alternatively, as a shortcut, the first line in your parser test file must be !! Version 2.

Enabling hooks

Abyste se ujistili, že se načte přípona tag1, přidejte na začátek souboru:

!! hooks
tag1
!! endhooks

Adding articles

In order to create a new article, the syntax is:

!! article
Template:Simple template
!! text
A ''simple'' template.
!! endarticle

Layout of a parser test

Besides the test time, a test has a given number of sections:

  • mandatory sections : wikitext
  • optional sections : options, config, wikitext/edited, html, html/php, html/parsoid, html/parsoid+standalone, html/parsoid+integrated

Sections specific to the legacy parser

The legacy parser expects the wikitext and one of html or html/php sections to be always present.

Sections specific to Parsoid

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. Since Parsoid supports running tests in different modes, the test modes determine what sections are expected.

Modes used for transformation between wikitext (wt) and html
from ↓ into → wt html
wt wt2wt wt2html
html html2wt html2html
  • For wt2html and html2wt modes, in addition to the wikitext section, at least one of html, html/parsoid, html/parsoid+standalone, or html/parsoid+integrated sections should be present.
  • For wt2wt mode, just the wikitext section is sufficient (but the test runner currently expects some html section to be present).
  • For html2html mode, one of the html sections is sufficient.
  • For selser modes[1], the wikitext and at least one of the html sections should be present.
  • For manual selser modes[1], the wikitext and wikitext/edited should both be present.

Example

Syntaxe pro jednoduchý test je následující.

!! 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

Pokud tam zadáte konfigurační nastavení, ujistěte se, že mezi výrazy nejsou žádné mezery, protože mezery nejsou oříznuty testovacím programem.

Options section

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 or parsoid={...} (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 modes: wt2html, wt2wt, html2wt, html2html, selser[1].[2]
    • 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 run
      • selser - If selser[1] 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 the changes property will be applied.
      • changes - This format is described separately below. This option will need to be paired with a wikitext/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.

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

  • wikitext - This is expected to be present in all tests that require the wikitext to be processed to HTML (or in Parsoid's html2wt and wt2wt test modes, the wikitext to generate from the HTML sections).
  • wikitext/edited - 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

  • html - This is the original default output section for a parser test. Parsoid only uses this section if there isn't any Parsoid-specific section available (see below). If Parsoid uses this section for a test, Parsoid will heavily normalize Parsoid's HTML output before comparing against this HTML. This is because Parsoid generates different markup for a lot of wikitext constructs. The normalization ensures the semantic attributes and properties (that don't have a rendering impact) don't cause false test failures.
  • html/php - This section is only used by the legacy parser and Parsoid ignores this.
  • html/parsoid - This is the default section used by Parsoid and is used for both standalone and integrated tests if specialized sections aren't present for those modes. The test runner will minimally normalize Parsoid's output and this section to verify test pass/fails. The normalization strips some noisy attributes to prevent the need to add all this noisy output to parser tests.
    • html/parsoid+standalone - This Parsoid HTML section is only used in Parsoid standalone test runs (only implemented in Parsoid's test runner).
    • html/parsoid+integrated - This Parsoid HTML section is only used in Parsoid integrated test runs (only implemented in the MediaWiki core's test runner).

Metadata sections

Previously, metadata was pre- or post- pended to the html sections but now get a dedicated section of its own. Parser tests are in the process of being migrated to the new format and backwards compatibility in the test runner still exists for tests written in the old way.

  • metadata - Collects metadata requested by the variations options, including cat, ill, property=, extension=, showtitle, showflags, showtocdata, showindicators, and showmedia.
  • Similar to the html, the standard variants to the sections exist, as in metadata/php, metadata/parsoid, metadata/parsoid+standalone, etc.

Enabling testing against Parsoid

You can enable running tests in a file against by Parsoid via the parsoid-compatible option in the file options section. You can specify individual modes or enable all modes by omitting the options string. For example parsoid-compatible=wt2html,wt2wt enables running Parsoid tests in wt2html and wt2wt modes. But, parsoid-compatible enables running Parsoid tests in all modes (wt2html, wt2wt, html2wt, html2html, selser).

See an example below.

!! options
version=2
parsoid-compatible=wt2html
!! end

extension.json & parser tests

U rozšíření, která umístí své testy do tests/parser/ a používají extension.json, se automaticky spustí testy analyzátoru. For extensions using the legacy extension loading system, they can use:

$wgParserTestFiles[] = __DIR__ . "/myParserTests.txt";

Running tests with parserTests.php

Chcete-li spustit testy analyzátoru, přejděte do kořenového adresáře místní instalace MediaWiki a z příkazového řádku proveďte následující:

php tests/parser/parserTests.php
Před MediaWiki 1.28 byl tento soubor umístěn na tests/parserTests.php.

Chcete-li spustit testy pouze pro jeden soubor, použijte --file=... param. Zobrazit další parametry pomocí --help.

php tests/parser/parserTests.php --file=extensions/Kartographer/tests/parser/parserTests.txt

Parsoid-specific test runner options

These options aren't available with MediaWiki core's parser 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

Nastavení globálních konfiguračních proměnných

Chcete-li nastavit výchozí globální proměnné pro všechny testy analyzátoru v rozšíření, použijte háček ParserTestGlobals .

V konkrétním testu nastavte konfigurační proměnné následovně:

!! test
Your Test Name
!! config
wgVariableName=true
!! wikitext
...

Související odkazy

References

  1. 1.0 1.1 1.2 1.3 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.
  2. TODO: Add a link to a wikipage that explains Parsoid's various transformations.