Manual:Parser tests/pt

The Parsoid -specific sections and Parsoid-specific options are only relevant for (a) Parser test files in the Parsoid repository (b) Parser test files that have been marked Parsoid-compatible. Also note that MW 1.38 and prior do not have support for running Parsoid tests via the parserTests.php test runner in MediaWiki core. But, these options are available in Parsoid's test runner (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 and the standalone parserTests.php script. So, a parser test failure will trigger a Jenkins test failure.

Sintaxe e execução

Opções do ficheiro de teste

A secção das opções contém opções que se aplicam a todo o ficheiro e a todos os testes contidas no mesmo.

Formato versão 2

A partir da versão 1.35, os testes do analisador têm de estar no formato da versão 2. Especificar a versão 2 indica que os testes estão prontos para serem executados no modo "ordenado" (Consulte T249138).

Para indicar que os seus testes do analisador são executados no formato da versão 2, pode utilizar a secção das opções no topo do ficheiro (ver em baixo).

!! options
version=2
!! end

Alternativamente, como um atalho, a primeira linha no seu teste do analisador deve ser !! Version 2.

Ativar os testes contra Parsoid

You can enable running tests in a file against 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. As a shortcut, parsoid-compatible without a value enables running Parsoid tests in all modes (wt2html, wt2wt, html2wt, html2html, selser).

See an example below.

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


Requisitos

Tests can require an extension to be loaded to run. If the extension is not loaded, the tests of the file are skipped. This behavior is not supported by the Parsoid stand-alone test runner, which will try (and probably fail) to execute said tests.

Por exemplo:

!! options
version=2
requirements=extension:ParserFunctions
!! end

Ativação de hooks

In order to be sure that the extension tag tag1 is loaded add at the beginning of the file:

!! hooks
tag1
!! endhooks

Adicionar artigos

Para poder criar um novo artigo, a sintaxe é:

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

Estrutura de um teste do analisador

Além da hora do teste, um teste tem uma série de secções:

  • secções obrigatórias : wikitext
  • secções opcionais : options, config, wikitext/edited, html, html/php, html/parsoid, html/parsoid+standalone, html/parsoid+integrated

Secções específicas para o analisador legado =

O analisador legado espera que estejam sempre presentes a secção wikitext e uma das secções html ou html/php.

Secções específicas para Parsoid =

A secção wikitext/edited e as diversas secções html/parsoid* só são relevantes quando executa um teste com Parsoid. Parsoid também permite uma configuração adicional com opções específicas para o teste na secção das opções. Porque Parsoid permite realizar testes em modos diferentes, estes determinam que secções se esperam.

Modos utilizados para a transformação ente o texto wiki (wt) e html
de ↓ para → 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.

Exemplo

A sintaxe para um teste simples é a seguinte:

!! Version 2
!! test
Simple paragraph
!! config
wgRestrictDisplayTitle=false
!! wikitext
This is a simple paragraph.
!! html
<p>This is a simple paragraph.
</p>
!! end

Secção da configuração

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.

Secção das opções

Each option should come on its own line.

  • disabled disables the test.
  • title= sets the name of the page that the test should be run with; the default is Parser_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.
  • Metadata options. Some keywords, such as cat (for categories) or showindicators can be added (each on their own line) to emit metadata to the test metadata results. The complete list of supported keywords is given in the documentation at the top of the Mediawiki /test/parser/parserTests.txt file. The emitted metadata will then be compared to the metadata section contents, if existing.

Altera o formato

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.


Secções do texto wiki

  • 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.

Secções de HTML

  • 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).

Secções de metadados

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, showmedia.
  • Similar to the html, the standard variants to the sections exist, as in metadata/php, metadata/parsoid, metadata/parsoid+standalone, etc.

Realce da sintaxe Vim

There is a vim syntax file for parserTests in the Parsoid repository, in tools/ptests.vim. Its installation is documented at the top of the file.

extension.json e testes do analisador

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";

Executar os testes com parserTests.php

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
Prior to MediaWiki 1.28, this file was located at 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

Opções do executor de teste específico de Parsoid

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

Definir as variáveis de configuração globais

Para definir as variáveis globais por predefinição para todos os testes do analisador numa extensão, utilize hook ParserTestGlobals.

Num teste específico, defina as variáveis de configuração como se segue:

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

Consultar também

Referências

Category:Testing/pt
  1. 1 2 3 4 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.
Category:Testing/pt