PrestaFlow : trois options CLI méconnues — --junit, --draft, --visual-report

Trois options qu’on a ignorées

Vingt-neuf articles plus tard, on a couvert --output=JSON, --file, --group, PRESTAFLOW_HEADLESS, PRESTAFLOW_DEBUG — l’essentiel de la CLI PrestaFlow. Trois options sont pourtant restées silencieuses :

--junit — écrit un rapport XML au format JUnit standard
--draft / -d — filtre les suites selon leur statut brouillon
--visual-report — génère un rapport HTML dédié aux régressions visuelles

Chacune répond à un besoin précis qu’aucune autre option ne couvre. Cette annexe les documente une par une.

`--junit` : intégrer avec un CI qui parle JUnit

Le format JUnit XML est le standard historique du reporting de tests. Jenkins l’affiche nativement (widget test results), GitLab CI l’ingère via artifacts:reports:junit, Azure DevOps et Bitbucket font pareil. Beaucoup d’outils de dashboards de tests (Allure, ReportPortal) le consomment aussi.

PrestaFlow sait le produire :

composer prestaflow -- run ./tests/prestaflow --junit

Écrit prestaflow/junit.xml par défaut. Ou path explicite :

composer prestaflow -- run ./tests/prestaflow --junit=reports/junit.xml

Le fichier suit la structure JUnit standard : un <testsuite> par suite exécutée, un <testcase> par it, avec <failure> / <skipped> selon l’état. Directement ingérable par n’importe quel outil qui parle JUnit.

Intégration GitLab CI

.gitlab-ci.yml — ajouter à un job PrestaFlow :

e2e:
  # ...
  script:
    - composer prestaflow -- run ./tests/prestaflow --junit=reports/junit.xml
  artifacts:
    when: always
    reports:
      junit: reports/junit.xml
    paths:
      - reports/

Résultat côté GitLab : l’onglet Tests de la pipeline affiche le récapitulatif natif — passes / failures / durée par it, avec drill-down sur les échecs. Pas de plugin, pas de script custom.

Intégration Jenkins

Dans un Jenkinsfile (voir aussi l’annexe CI hors GitHub Actions) :

post {
    always {
        junit 'reports/junit.xml'
    }
}

Le widget Test Result Trend de Jenkins accumule les résultats sur les runs successifs et trace le graphe des passes/failures.

JUnit vs `results.json`

L’annexe consommer results.json a montré le format JSON riche de PrestaFlow. JUnit est complémentaire, pas concurrent :

JUnit — format standard, consommé passivement par vos outils CI existants (dashboards, historique, alertes)
results.json — format PrestaFlow, consommé activement par vos scripts custom (Slack, badge README, dashboard maison)

Rien n’empêche d’activer les deux dans le même run : --junit --output=JSON --file produit les deux fichiers, chacun pour son usage. Petite différence à connaître en v1.7.1 : junit.xml couvre toutes les suites du run, alors que results.json ne garde que la dernière suite exécutée.

`--draft` / `-d` : isoler les brouillons

Un scénario que vous êtes en train d’écrire n’est pas fait pour tourner en CI ni pour rougir tous les runs de votre équipe. Vous voulez pouvoir le committer sans qu’il pollue le reste — jusqu’à ce qu’il soit prêt.

PrestaFlow expose un statut draft au niveau de la suite, activé via une propriété :

class WorkInProgressCheckoutV2 extends TestsSuite
{
    protected $draft = true;

    public function init()
    {
        // scénario en cours d'écriture, sélecteurs qui bougent
    }
}

Combiné avec le flag CLI qui prend trois formes :

--draft — ne joue que les suites $draft = true. Utile en dev pour boucler sur le scénario en cours d’écriture, sans réexécuter les 40 suites stables du reste du projet.
--no-draft — ne joue que les suites $draft = false (défaut de la classe). C’est ce que le CI devrait passer pour être imperméable aux brouillons committés.
Sans flag — joue tout, drafts inclus. Comportement neutre, comme si l’option n’existait pas.

Workflow suggéré

En dev local : composer prestaflow -- run ./tests/prestaflow --draft pendant qu’on itère sur un scénario neuf.
En CI (workflow principal) : --no-draft pour ignorer les brouillons et garantir la stabilité.
En CI (workflow nightly optionnel) : sans flag, pour un run complet qui inclut aussi les drafts et donne un signal sur leur maturité.

Une fois le scénario stable, on retire $draft = true de la classe. Le scénario devient normal, il tourne dans le CI principal.

`--visual-report` : un rapport dédié aux visuels

L’annexe régressions visuelles a introduit visualCheckpoint(). Leurs résultats apparaissent dans la sortie console des tests, mêlés aux assertions fonctionnelles, et dans le bloc visual du results.json. Utile en debug — moins utile quand un reviewer non-technique doit valider ou rejeter une série de diffs visuels.

Le flag --visual-report produit un rapport HTML séparé, dédié uniquement aux régressions visuelles :

composer prestaflow -- run ./tests/prestaflow --visual-report

Écrit reports/visual/index.html par défaut. Ou path explicite :

composer prestaflow -- run ./tests/prestaflow --visual-report=public/visual-latest.html

Le rapport présente les checkpoints en cartes visuelles : référence / actuelle / diff en vignettes côte à côte (images embarquées dans le HTML), score de similarité et statut (conforme, écart, baseline créée). Le seuil utilisé n’y figure pas. C’est le format à envoyer au designer ou au chef de projet qui doit trancher « ce changement de padding est-il volontaire ? ».

Un fichier visual-results.json est écrit dans le même dossier (par exemple reports/visual/visual-results.json) — machine-readable si vous voulez automatiser une décision : date de génération, puis nom, statut et score de chaque checkpoint.

Fuseau horaire du stamp

Par défaut, le stamp « généré le X » du rapport est en UTC. Deux manières de contrôler :

# Via env var (globale)
PRESTAFLOW_TZ=Europe/Brussels composer prestaflow -- run ./tests/prestaflow --visual-report

# Via option CLI (spécifique au run)
composer prestaflow -- run ./tests/prestaflow --visual-report --visual-report-tz=Europe/Brussels

L’option CLI gagne sur l’env var, l’env var gagne sur UTC. Si l’identifiant de fuseau est invalide, PrestaFlow retombe silencieusement sur UTC — le rapport est toujours généré.

Combiner les trois

Les trois options sont indépendantes et se cumulent :

composer prestaflow -- run ./tests/prestaflow \
  --no-draft \
  --junit=reports/junit.xml \
  --visual-report=reports/visual/index.html \
  --output=JSON --file

Un seul run produit :

La sortie console habituelle
Le fichier results.json (--output=JSON --file)
Le rapport JUnit XML (--junit)
Le rapport visuel HTML dédié + son JSON (--visual-report)

Chacun pour son usage — la console pour l’humain qui debug, le JSON pour les scripts custom, le JUnit pour le CI qui l’ingère nativement, le visual pour la revue humaine des baselines.

Interaction avec les autres annexes

CI hors GitHub Actions — GitLab CI et Jenkins ont un support natif de JUnit qui rend --junit immédiatement rentable. Sur GitHub Actions, le support natif JUnit est moins riche (il faut une action tierce, type dorny/test-reporter) — l’--output=JSON reste souvent plus adapté.
Consommer results.json — les deux formats se cumulent, chacun a son bon usage.
Régressions visuelles — --visual-report est le compagnon naturel de visualCheckpoint(). Sans checkpoints visuels dans vos suites, le rapport est vide.
Consulter l’historique cloud — la plateforme prestaflow.io consomme le results.json, pas le JUnit ni le visual-report HTML. Ces derniers restent des artefacts locaux ou CI.