Manual:Pruebas del analizador sintáctico
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.
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,[1] debe estar presente la sección wikitext y al menos una de las secciones html.
- Para los modos manuales selser,[1] 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 esParser_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
oparsoid={...}
(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.[1].[2] - 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[1] 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 propiedadchanges
.changes
- Este formato se describe por separado a continuación. Esta opción debe emparejarse con una secciónwikitext/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.
- P. ej.,
- Opciones de metadatos. Se pueden añadir algunas palabras clave, como
cat
(para categorías) oshowindicators
, 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, comocat
,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
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
Referencias
- ↑ 1.0 1.1 1.2 1.3 El modo selser es una abreviatura del modo de prueba en que se edita la sección HTML de varias maneras automatizadas y luego se convierte en wikitexto mediante las transformaciones de serialización selectiva (en adelante, selser) de Parsoid.
- ↑
TODO: Añadir un enlace a una wikipágina que explique las distintas transformaciones de Parsoid.