Rapports de tests PHP dans GitLab CI

Publié le 22/10/2020 à 18:09. Mise à jour le 22/10/2020 à 18:13.

Les tests, c'est bien, avec des rapports, c'est mieux !

Rapports de tests PHP dans GitLab CI

Photo par Gabriel Sollmann sur Unsplash

Dans une pipeline d'integration continue on va au minimum exécuter des suites de tests. Mais on peut rajouter d'autres outils: analyse statique, verification de syntaxe, ...

Si l'un des job échoue, le code peut être considéré instable et on ne déploie ou ne livre pas si c'était prévu dans les stages suivants.

Dans tous les cas, ce peut être pratique de voir via l'interface de l'outil de CI ce qui a échoué, sans avoir à fouiller dans les logs de chaque job.
C'est ce qu'on va voir avec des outils PHP sur GitLab CI.

Cet article ne montre pas comment configurer ces outils mais uniquement leur integration avec GitLab.

Les artéfacts et le format JUnit

Les artéfacts dans GitLab CI

Les artéfacts sont des fichiers ou dossiers enregistrés à la fin de l'exécution d'un job. Ils seront ensuite disponibles via l'interface GitLab pour les télécharger.
On les déclare dans la section artifacts de chaque job.

On peut s'en servir pour enregistrer tous documents générés ou programmes construits dans un job.

Il faut noter également qu'un artéfact est automatiquement disponible dans les jobs des stages suivant celui dans lequel il a été créé.
(voir Utilisation de cache avec GitLab CI en Docker-in-Docker à la section «l'alternative save / load »)

Les rapports de test au format JUnit

Le fichier gitlab-ci.yml prevoit plusieurs sous sections dans artifacts.
Une clé reports permet de lister des rapports de test ou de qualité de code, sous laquelle on peut ajouter une clé junit pour les rapports au format JUnit:

test_job:
    artifacts:
        reports:
            junit:
                - report.xml

Les raports de test sont collectés meme si le job échoue.

Les rapports JUnit sont des fichiers XML listant les tests exécutés. Les tests seront ensuite affichés dans l'interface GitLab dans l'onglet « Tests » des pages de pipelines.
JUnit vient de Java mais le format est largement utilisé, on fera donc exporter nos rapports sous celui-ci.

PHPUnit

Exécuter ses tests unitaires

En exécutant une suite de tests, on peut demander la création d'un rapport JUnit avec l'option --log-junit suivi d'un nom de fichier:

phpunit:
    artifacts:
        reports:
            junit: phpunit-report.xml
    script:
        - ./vendor/bin/phpunit --log-junit phpunit-report.xml

Si les tests sont exécutés depuis un conteneur Docker, le rapport sera créé dans celui-ci, il faudra donc l'exporter:

phpunit:
    artifacts:
        reports:
            junit: phpunit-report.xml
    before_script:
        - *docker-login
        - docker run -d $DOCKER_CI_IMAGE
    script:
        - docker exec app ./vendor/bin/phpunit --log-junit phpunit-report.xml
    after_script:
        - docker cp app:/path/to/phpunit-report.xml .

Pour bien comprendre l'ancre docker-login et la variable DOCKER_CI_IMAGE, voir cet article.

Enregistrer le taux de couverture du code

PHPUnit permet de générer un rapport de couverture de code (à condition d'avoir Xdebug, PCOV ou PHPDBG). GitLab est capable de récupérer ce rapport si le projet est configuré pour.
En allant dans les paramètres de CI/CD, dans le section « General Pipelines » , on retrouve une section « Test coverage parsing » avec des exemples.
Pour PHPUnit, insérer la RegEx suivante:

^\s*Lines:\s*\d+.\d+\%

Dans les jobs, on ajoutera quelques options pour générer un rapport de couverture de code en format texte:

./vendor/bin/phpunit --coverage-text --colors=never

Combinez-les avec les options du rapport JUnit !

Et si vous appréciez décorer vos README avec des badges, la section « Coverage report » apporte quelques exemples:

[![coverage report](https://gitlab.com/my-group/my-project/badges/master/coverage.svg)](https://gitlab.com/my-group/my-project/-/commits/master)

PHPStan

Comme pour PHPUnit, on peut générer un rapport JUnit avec PHPStan en utilisant l'option --error-format:

phpstan:
    artifacts:
        reports:
            junit:
                - phpstan.xml
    script:
        - ./vendor/bin/phpstan analyse --error-format=junit --no-progress -c ./phpstan.neon > phpstan.xml

Pour PHPStan la commande reste la même si on l'exécute depuis un conteneur Docker.

PHP CodeSniffer

Là encore, PHP_CodeSniffer permet la génération de rapport JUnit de la même manière que PHPStan, avec l'option --report:

php_codesniffer:
    artifacts:
        reports:
            junit:
                - phpcs-report.xml
    script:
        - ./vendor/bin/phpcs --report=junit > phpcs-report.xml

Conclusion

Je n'ai présenté ici que quelques outils, vous en utilisez peut-être d'autres (Psalm, Behat, PHPSpec, ...), vérifiez donc s'ils permettent la génération de rapports JUnit !

La phase de test est importante en CI, mais elle est toujours mieux si les outils de test et d'analyse sont bien intégrés à la plateforme de CI.

Commentaires: 0

Invasion robot en provenance de robohash.org