Manuel:Tests de l'analyseur syntaxique

Les sections spécifiques à Parsoid et à ses options ne concernent que : (a) les fichiers de test de l'analyseur du répertoire Parsoid, (b) les fichiers de test de l'analyseur qui ont été marqués compatibles avec Parsoid. Notez également que MW 1.38 et les précédents n'ont pas de support pour exécuter les tests Parsoid via le lanceur de test parserTests.php dans le noyau MediaWiki. Mais ces options sont disponibles dans le lanceur de test Parsoid (bin/parserTests.php dans le répertoire de Parsoid).

Le plus souvent, les cas de test de l'analyseur spécifie le wikicode (l'entrée généralement) et le HTML (la sortie généralement), pour confirmer que les choses se déroulent comme on les attend. La sortie courante est comparée au résultat souhaité, et ainsi les cas de test de l'analyseur (connus également sous le nom de tests de l'analyseur) peuvent être utiles pour détecter les régressions.

Les cas de test de l'analyseur sont rangés dans le répertoire tests/parser/. Les extensions doivent placer leurs tests dans un répertoire tests/parser/.

Vous pouvez à la fois faire les tests en utilisant la suite de tests unitaires de php, ou bien utiliser parserTests.php de manière indépendante. Ainsi un test en échec de l'analyseur déclenchera une erreur de test dans Jenkins.

Syntaxe et exécution

Format version 2

A partir de la 1.35, les tests de l'analyseur doivent se faire avec le format version 2. En précisant la version 2 vous indiquez que les tests sont utilisables en mode nettoyé (voir la tâche T249138).

Pour indiquer que vos tests de l'analyseur sont à exécuter au format version 2, vous pouvez utiliser la section des options du début de fichier (voir ci-dessous).

!! options
version=2
!! end

Eventuellement, en tant que raccourci, vous pouvez mettre !! Version 2 sur la première ligne de votre fichier de test de l'analyseur

Activer des points d’ancrage

Pour être sûr que la balise d'extension tag1 soit chargée, ajoutez au début du fichier :

!! hooks
tag1
!! endhooks

Ajouter des articles

Pour créer de nouveaux articles, la syntaxe est :

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

Structure d'un test d'analyseur

En plus de l'heure du test, un test possède un certain nombre de sections :

• sections obligatoires : wikitext
• sections facultatives : options, config, wikitext/edited, html, html/php, html/parsoid, html/parsoid+standalone, html/parsoid+integrated

Sections spécifiques à l'ancien analyseur

L'ancien analyseur s'attend toujours à trouver la section wikitext et une des sections html ou html/php.

Sections spécifiques à Parsoid

Les sections wikitext/edited et les différentes sections html/parsoid* n'ont de sens que pour les tests lancés avec Parsoid. Parsoid permet aussi une configuration supplémentaire avec des options supplémentaires spécifiques au test, dans la section des options. Parce que Parsoid permet de lancer les tests selon différents modes, ces derniers vont déterminer les sections attendues.

Modes utilisés dans les transformations entre wikicode (wt) et html

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

• Pour les modes wt2html et html2wt, en plus de la section wikitext, au moins une des sections html, html/parsoid, html/parsoid+standalone, ou html/parsoid+integrated doit être présente.
• Pour le mode wt2wt, seule la section wikitext est suffisante (mais le lanceur de test s'attend à trouver actuellement une section html présente).
• Pour le mode html2html, une des sections html est suffisante.
• Pour les modes selser, les sections wikitext et au moins une des sections html doivent être présentes.
• Pour les modes manuels selser, wikitext et wikitext/edited doivent être présents ensemble.

Exemple

La syntaxe pour un test simple est la suivante :

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

Section de configuration

Si vous spécifiez les paramètres de configuration ici, assurez-vous qu'il n'y ait aucun espace entre les expressions parce que l'espace n'est pas supprimé par le lanceur de tests.

Section des options

Chaque option doit être sur une ligne séparée.

• disabled désactive le test.
• php exécute le test uniquement avec l'analyseur par défaut du noyau, sauf s'il existe des sections HTML spécifiques à Parsoid. Le nom php est un vestige du passé, lorsque Parsoid était une base de code Node.js.
• parsoid=comma-separated-modes ou parsoid={...} (objet au format JSON) active les options spécifiques à Parsoid.
  • Exemple : parsoid=wt2html,wt2wt exécute ce test uniquement dans ces deux modes. Par défaut, le test est exécuté dans tous les modes de test disponibles et indiqués dans les sections wikitext et html. Généralement, cela équivaut à exécuter le test dans les modes suivants : wt2html, wt2wt, html2wt, html2html, selser.
  • Dans l'objet format JSON, les clés suivantes sont actuellement reconnues modes, selser, changes, suppressErrors, normalizePhp,
    • modes - Ceci est une liste de modes Parsoid à exécuter.
    • selser - Si selser est l'un des modes de test de la propriété modes, celle-ci peut spécifier optionnellement "noauto" pour indiquer que les modifications automatiques pour ce test ne doivent pas être générées. Si c'est le cas, seules les modifications manuelles telles que celles spécifiées par la propriété changes, seront appliquées.
    • changes - Ce format est décrit séparément ci-dessous. Cette option doit être appairée à une section wikitext/edited dans le test (voir ci-dessous) qui spécifie la sortie wikicode attendue quand ce HTML modifié est converti (via selser) en wikicode par Parsoid.

Format changes

Tableau de modifications individuelles à appliquer au DOM du HTML généré par le wikicode transformé. Chaque élément du tableau contient 3 éléments ou plus : (a) un sélecteur jquery pour sélectionner le noeud DOM, (b) le type de modification à appliquer au noeud sélectionné, (c) les valeurs correspondantes ou le contenu à appliquer à la modification spécifiée.

Plus simplement, chaque élément du tableau représente un appel de méthode jquery . Ainsi, [x,y,z...] devient $(x)[y](z....) donc, ['fig', 'attr', 'width', '120'] est interprété comme $('fig').attr('width', '120')

Actuellement seules les méthodes jquery suivantes sont reconnues : after, addClass, append, attr, before, empty, html, remove, removeAttr, removeClass, text, wrap

Voir http://api.jquery.com/ pour la documentation de ces méthodes.

« contents » en tant que second argument appelle la méthode jquery .contents() sur les résultats du sélecteur du premier argument, ce qui est une bonne manière d'obtenir le texte et les noeuds de commentaire.

Sections wikicode

• wikitext - Ceci est supposé être présent dans tous les tests qui nécessitent le wikicode à convertir en HTML (ou dans les modes html2wt et wt2wt de Parsoid, le wikicode à générer à partir des sections HTML).
• wikitext/edited - Cette section ne concerne que l'exécution des tests Parsoid. Pour les tests qui fournissent un ensemble manuel de modifications à appliquer au HTML généré de la section wikitext, ceci est la sortie attendue quand Parsoid reconvertit ce HTML modifié en wikicode.

Sections HTML

• html - Voici la section de sortie originale par défaut pour un test d'analyseur. Parsoid n'utilise cette section que s'il n'y a aucune section Parsoid spécifique disponible (voir ci-dessous). Si Parsoid utilise cette section pour un test, Parsoid aura des difficultés pour normaliser la sortie HTML de Parsoid avant de la comparer à ce HTML. Ceci est dû à ce que Parsoid génère différentes balises pour un grand nombre de constructions de wikicode. La normalisation assure que les attributs sémantiques et les propriétés (qui n'influencent pas le rendu) ne créeront pas de tests en faute.
• html/php - Cette section n'est utilisée que par l'ancien analyseur; elle est ignorée par Parsoid.
• html/parsoid - Ceci est la section par défaut utilisée par Parsoid et elle est utilisée à la fois pour des tests unitaires (standalone) et pour les tests d'intégration si les sections dédiées sont absentes pour ces modes. Le lanceur de tests va normaliser de manière minimale la sortie de Parsoid et de cette section pour vérifier si le test a réussi ou a échoué. La normalisation supprime certains attributs verbeux pour empêcher d'avoir à ajouter toutes ces informations aux tests de l'analyseur.
  • html/parsoid+standalone - Cette section HTML de Parsoid est utilisée uniquement dans les tests standalone de Parsoid (uniquement implémenté dans le lanceur de tests de Parsoid).
  • html/parsoid+integrated - Cette section HTML de Parsoid n'est utilisée que dans les tests d'intégration de Parsoid (implémenté uniquement dans le lanceur de tests du noyau MediaWiki).

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.

Autoriser les tests de Parsoid

Vous pouvez faire exécuter avec Parsoid tous les tests d'un fichier en utilisant l'option parsoid-compatible dans la section des options des fichiers. Vous pouvez spécifier des modes individuels, ou autoriser tous les modes en ne mettant aucune option. Par exemple parsoid-compatible=wt2html,wt2wt permet d'exécuter les tests Parsoid dans les modes wt2html et wt2wt. Mais parsoid-compatible permet d'exécuter les tests Parsoid dans tous les modes (wt2html, wt2wt, html2wt, html2html, selser).

Voir l'exemple ci-dessous.

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

extension.json et tests de l'analyseur

Les extensions qui enregistrent leurs tests dans tests/parser/ et qui utilisent extension.json auront leurs tests d'analyseur automatiquement activés. Les extensions qui se servent de l'ancien système de chargement des extensions peuvent utiliser :

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

Exécuter les tests avec parserTests.php

Pour exécuter les tests de l'analyseur, allez dans le répertoire de votre installation locale MediaWiki et exécutez les instructions suivantes à partir de la ligne de commande :

php tests/parser/parserTests.php

Avant MediaWiki 1.28, ce fichier était dans tests/parserTests.php.

Pour exécuter les tests juste sur un seul fichier, utilisez le paramètre --file=... . Voir --help pour les autres paramètres.

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

Options particulières au lanceur de test de Parsoid

Ces options ne sont pas disponibles avec le lanceur de tests de l'analyseur du noyau MediaWiki en MW 1.38 et auparavent. Vous pouvez lancer les tests en mode Parsoid via l'option --parsoid. La meilleure documentation et la plus actuelle concernant toutes les options est donnée par :

php tests/parser/parserTests.php --help

Initialisation des paramètres de configuration globaux

Pour initialiser les variables globales par défaut pour tous les tests de l'analyseur dans une extension, utilisez l'accroche ParserTestGlobals .

Pour un test donné, initialisez les paramètres de configuration ainsi :

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

Voir aussi

• Tests unitaires