Manual:Pruebas del analizador sintáctico

Las secciones y opciones específicas de Parsoid solo son relevantes para (a) archivos de pruebas del analizador sintáctico en el repositorio de Parsoid y (b) archivos de pruebas del analizador sintáctico que se han marcado como compatibles con Parsoid. Además, ten en cuenta que MW 1.38 y anteriores no tienen soporte para la ejecución de pruebas de Parsoid mediante el lanzador de pruebas parserTests.php en el núcleo de MediaWiki. Sin embargo, estas opciones están disponibles en el lanzador de pruebas de Parsoid (bin/parserTests.php en el repositorio de Parsoid).

Generalmente, los casos de prueba del analizador sintáctico especifican wikitexto (habitualmente la entrada) y HTML (habitualmente la salida) para confirmar que todo se desarrolla según lo esperado. La salida real se compara con el resultado deseado, y así, los casos de prueba del analizador (también conocidos como pruebas del analizador) pueden ser útiles para detectar regresiones.

Los casos de prueba del analizador residen en el directorio tests/parser/. Las extensiones deberían situar sus pruebas en un directorio tests/parser/.

Pueden ejecutarse tanto a través de la suite de pruebas PHPUnit como a través del script independiente parserTests.php. Así que un fallo en una prueba del analizador provocará un fallo en una prueba de Jenkins.

Sintaxis y ejecución

Opciones del archivo de prueba

La sección de opciones contiene opciones que se aplican a todo el archivo y a todas las pruebas contenidas en él.

Formato versión 2

A partir de 1.35, se requiere que las pruebas del analizador estén en el formato versión 2. Especificar la versión 2 indica que las pruebas están listas para ejecutarse en modo ordenado o tidy (véase T249138).

Para indicar que tus pruebas del analizador se ejecuten en el formato versión 2, puedes utilizar la sección de opciones en el inicio del archivo (ver a continuación).

!! options
version=2
!! end

Alternativamente, a modo de atajo, la primera línea de tu archivo de pruebas del analizador debe ser !! Version 2.

Activar las pruebas contra Parsoid

Puedes activar la ejecución de pruebas en un archivo contra Parsoid mediante la opción parsoid-compatible en la sección de opciones de archivo. Puedes especificar modos individuales o activarlos todos omitiendo la cadena options. Por ejemplo, parsoid-compatible=wt2html,wt2wt permite ejecutar pruebas de Parsoid en los modos wt2html y wt2wt. A modo de atajo, parsoid-compatible sin valor permite ejecutar pruebas de Parsoid en todos los modos (wt2html, wt2wt, html2wt, html2html, selser).

Véase el ejemplo a continuación.

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

Requisitos

La ejecución de las pruebas puede requerir que se haya cargado una extensión. Si la extensión no está cargada, se omitirán las pruebas del archivo. Este comportamiento no está soportado por el lanzador de pruebas independiente, que intentará (y probablemente fracasará) ejecutar dichas pruebas.

Por ejemplo:

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

Activar enganches

Para asegurarte de que la etiqueta de extensión tag1 está cargada, añade lo siguiente al principio del archivo:

!! hooks
tag1
!! endhooks

Añadir artículos

Para crear un nuevo artículo, la sintaxis es:

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

Estructura de una prueba del analizador

Además de la hora, una prueba tiene una serie de secciones:

• secciones obligatorias: wikitext
• secciones opcionales: options, config, wikitext/edited, html, html/php, html/parsoid, html/parsoid+standalone, html/parsoid+integrated

Secciones específicas del antiguo analizador

El antiguo analizador espera que siempre estén presentes la sección wikitext y una de las secciones html y html/php.

Secciones específicas de Parsoid

La sección wikitext/edited y las diversas secciones html/parsoid* solo son relevantes a la hora de realizar una prueba con Parsoid. Parsoid también permite una configuración adicional con opciones específicas para la prueba en la sección de opciones. Dado que Parsoid permite realizar pruebas en distintos modos, los modos determinan qué secciones se esperan.

Modos utilizados para transformaciones entre wikitexto (wt) y html

de ↓ a →	wt	html
wt	wt2wt	wt2html
html	html2wt	html2html

• Para los modos wt2html y html2wt, además de la sección wikitext, debe estar presente al menos una de las secciones html, html/parsoid, html/parsoid+standalone o html/parsoid+integrated.
• Para el modo wt2wt, basta con la sección wikitext (aunque el lanzador de pruebas actualmente espera que esté presente alguna sección html).
• Para el modo html2html, basta con una de las secciones html.
• Para los modos selser, debe estar presente la sección wikitext y al menos una de las secciones html.
• Para los modos manuales selser, deben estar presentes tanto wikitext como wikitext/edited.

Ejemplo

La sintaxis para una prueba simple es la siguiente:

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

Sección de configuración

Si especificas parámetros de configuración allí, asegúrate de que no haya espacio en blanco entre tus expresiones, ya que el lanzador de pruebas no lo elimina.

Sección de opciones

Cada opción debería estar en una línea separada.

• disabled desactiva la prueba.
• title= establece el nombre de la página con la que se debería ejecutar la prueba; el valor por defecto es Parser_test.
• php ejecuta la prueba solo con el analizador predeterminado del núcleo salvo que estén presentes secciones HTML específicas de Parsoid. El nombre php es un vestigio histórico de cuando Parsoid era una base de código de Node.js.
• parsoid=comma-separated-modes o parsoid={...} (objeto en formato JSON) habilita las opciones específicas de Parsoid.
  • P. ej., parsoid=wt2html,wt2wt ejecuta esta prueba solamente en estos dos modos. Por defecto, se ejecuta la prueba en todos los modos disponibles para la misma dadas las secciones de wikitexto y html. En el caso general, esto equivale a ejecutar la prueba en los modos wt2html, wt2wt, html2wt, html2html, selser..
  • En el objeto en formato JSON, las siguientes claves están actualmente reconocidas: modes, selser, changes, suppressErrors, normalizePhp,.
    • modes - Esta es una lista de modos de Parsoid, separados por comas, para ejecutar.
    • selser - Si selser es uno de los modos de prueba en la propiedad modes, esta propiedad puede especificar opcionalmente "noauto" para indicar que no se deben generar ediciones automáticas para esta prueba. En ese caso, solo se aplicarán las ediciones manuales tal como especifica la propiedad changes.
    • changes - Este formato se describe por separado a continuación. Esta opción debe emparejarse con una sección wikitext/edited en la prueba (véase a continuación) que especifique la salida de wikitexto esperada cuando Parsoid haya convertido (mediante selser) a wikitexto este HTML editado.
• Opciones de metadatos. Se pueden añadir algunas palabras clave, como cat (para categorías) o showindicators, cada una en su propia línea, para emitir metadatos a los resultados de metadatos de las pruebas. La lista completa de palabras clave con soporte se encuentra en la documentación, en la parte superior del archivo /test/parser/parserTests.txt de MediaWiki. Los metadatos emitidos se compararán entonces con el contenido de la sección de metadatos, en caso de existir.

Formato changes

Este es un vector de cambios individuales por aplicar al DOM del HTML generado al transformar el wikitexto. Cada elemento del vector contiene tres o más elementos: (a) un selector jQuery para seleccionar un nodo del DOM, (b) el tipo de cambio por aplicar al nodo seleccionado, (c) los valores pertinentes o el contenido necesario para aplicar el cambio especificado.

De forma más sucinta, cada elemento del vector representa una llamada a un método jQuery. De este modo, [x,y,z...] se convierte en $(x)[y](z....), por lo que ['fig', 'attr', 'width', '120'] se interpreta como $('fig').attr('width', '120').

Actualmente, se reconocen los siguientes métodos de jQuery: after, addClass, append, attr, before, empty, html, remove, removeAttr, removeClass, text, wrap.

Consulta http://api.jquery.com/ para la documentación de dichos métodos.

«contents» como segundo argumento llama al método jquery .contents() sobre los resultados del selector en el primer argumento, lo cual es una buena manera de llegar a los nodos de texto y comentarios.

Secciones de wikitexto

• wikitext - Esto se espera que esté presente en todas las pruebas que requieran que se procese el wikitexto a HTML (o, en los modos de pruebas de Parsoid html2wt y wt2wt, que se genere el wikitexto a partir de las secciones HTML).
• wikitext/edited - Esta sección solo es relevante en los lanzamientos de pruebas de Parsoid. Para las pruebas que proporcionan un conjunto de cambios manuales que aplicar al HTML generado a partir de la sección wikitext, esta es la salida esperada cuando Parsoid convierte dicho HTML editado de vuelta a wikitexto.

Secciones HTML

• html - Esta es la sección de salida original por defecto para una prueba del analizador. Parsoid solo utiliza esta sección si no hay ninguna sección disponible específica de Parsoid (véase a continuación). En caso de que Parsoid utilice esta sección para una prueba, normalizará significativamente la salida HTML antes de compararla con este HTML. Esto se debe a que Parsoid genera marcados diferentes para numerosos constructos de wikitexto. La normalización asegura que los atributos y propiedades semánticos (que no tienen un impacto en la renderización) no provoquen falsos fallos en las pruebas.
• html/php - Esta sección solo es utilizada por el antiguo analizador; Parsoid la ignora.
• html/parsoid - Esta es la sección predeterminada utilizada por Parsoid y se utiliza tanto para pruebas unitarias como para pruebas integradas si no hay secciones especializadas presentes para estos modos. El lanzador de pruebas normalizará mínimamente la salida de Parsoid y esta sección para verificar éxitos y fallos. La normalización elimina algunos atributos verbosos para evitar la necesidad de añadir toda esta salida verbosa a las pruebas del analizador.
  • html/parsoid+standalone - Esta sección HTML de Parsoid solo se utiliza en lanzamientos de pruebas unitarias de Parsoid (solo está implementada en el lanzador de pruebas de Parsoid).
  • html/parsoid+integrated - Esta sección HTML de Parsoid solo se utiliza en lanzamientos de pruebas integradas de Parsoid (solo está implementada en el lanzador de pruebas del núcleo de MediaWiki).

Secciones de metadatos

En el pasado, los metadatos se anteponían o se posponían a las secciones HTML, pero ahora disponen de una sección dedicada. Las pruebas del analizador están en proceso de migrar al nuevo formato, y aún existe una retrocompatibilidad en el lanzador de pruebas para las pruebas escritas de la forma anterior.

• metadata - Colecciona los metadatos solicitados por las opciones de variaciones, como cat, ill, property=, extension=, showtitle, showflags, showtocdata, showindicators, showmedia.
• Similar al HTML, las variantes estándar de las secciones existen, como por ejemplo en metadata/php, metadata/parsoid, metadata/parsoid+standalone, etc.

Resaltado sintáctico en vim

Hay un archivo de sintaxis de vim para parserTests en el repositorio de Parsoid, en tools/ptests.vim. Su instalación está documentada al principio del archivo.

extension.json y las pruebas del analizador

Las extensiones que sitúen sus pruebas en tests/parser/ y utilicen extension.json tendrán activado automáticamente el lanzamiento de sus pruebas del analizador. Para las extensiones que utilicen el antiguo sistema de carga de extensiones, pueden utilizar:

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

Lanzar pruebas con parserTests.php

Para lanzar las pruebas del analizador, ve al directorio raíz de tu instalación local de MediaWiki y ejecuta lo siguiente desde la línea de comandos:

php tests/parser/parserTests.php

En versiones anteriores a MediaWiki 1.28, este archivo se encontraba en tests/parserTests.php.

Para lanzar pruebas para un solo archivo, utiliza el parámetro --file=.... Consulta --help para los demás parámetros.

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

Opciones específicas del lanzador de pruebas de Parsoid

Estas opciones no están disponibles con el lanzador de pruebas del analizador del núcleo de MediaWiki en MW 1.38 y anteriores. Puedes lanzar las pruebas en el modo de Parsoid mediante la opción --parsoid. La mejor documentación, así como la más actualizada de todas las opciones disponibles, pasa por ejecutar

php tests/parser/parserTests.php --help

Inicializar variables de configuración globales

Para establecer variables globales por defecto para todas las pruebas del analizador en una extensión, utiliza el enganche ParserTestGlobals .

En una prueba determinada, establece las variables de configuración como sigue:

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

Véase también

• Manual:Pruebas unitarias