FAQ : Quelques détails techniques

Comment extraire le contenu d'un fichier tar ?

Certains rapports (par exemple les rapports Allure) sont stockés dans un fichier tar.
Il existe plusieurs façons d'extraire le contenu d'un tel fichier tar.

Utilisation de 7-Zip

Téléchargez et installer le logiciel 7-Zip.
Lancez le programme 7-Zip.
Dans son navigateur de fichiers, naviguez jusqu'au répertoire contenant le fichier tar.
Sélectionnez le fichier tar dans le navigateur de fichiers.
Cliquez sur le bouton "Extraire" pour extraire le contenu du fichier tar.

Utilisation de WinZip

Téléchargez et installer le logiciel WinZip.
Lancez le programme WinZip.
Naviguez jusqu'au fichier tar dans le navigateur de la fenêtre principale.
Cliquez sur le bouton "Décompresser" pour extraire le contenu du fichier tar.

Utilisation de la commande `tar`

Si vous êtes sur Linux ou MacOS ou, sur Windows, si vous avez MinGW/MSYS, Cygwin ou WSL2 installé, vous pouvez utiliser la commande tar : tar xvf <fichier tar>.

Comment afficher un rapport Allure ?

Obsolescence des rapports Allure

Depuis la livraison 2024-03, Squash Orchestrator peut générer un rapport HTML offrant un aperçu complet des tests d'un workflow. Il s'agit d'une fonctionnalité redondante avec les rapports Allure, mais ceux de l'orchestrateur sont plus polyvalents et pourront être encore étendus à l'avenir. Nous prévoyons donc de supprimer la prise en charge des rapports Allure :

Au quatrième trimestre 2024, l'orchestrateur cessera de générer des rapports Allure par défaut. La génération pourra être réactivée par configuration.
Au troisième trimestre 2025, la prise en charge des rapports Allure sera abandonnée. Aucun rapport Allure ne pourra plus être créé.

Installation d'Allure

La documentation d'Allure indique comment l'installer.

Affichage d'un rapport Allure

Télécharger le fichier depuis Squash en cliquant sur son nom Téléchargement du rapport Allure Extrayez le contenu du fichier tar, cela va créer un répertoire allure-report.
Ouvrez une fenêtre de commandes et naviguez jusqu'au répertoire contenant le répertoire allure-report.
Exécutez la commande allure open.
Ouverture du rapport Allure Votre navigateur va s'ouvrir en affichant le rapport Allure.

Comment mettre en place un hook ?

Les hooks définissent les actions lancées au début et/ou à la fin de l'exécution de chaque test. On peut les utiliser, entre autres, pour remonter des fichiers créés en cours de l'exécution vers Squash.

Les hooks ont la structure suivante :

- name: 
  events:
  if:
  before:
  after:

Les paramètres name et events sont obligatoires, de même que l'un des paramètres before ou after.

Il existe deux possibilités pour mettre en place un hook :

Déclarer le hook dans la section hooks du fichier de configuration du provider. Ce fichier se trouve typiquement dans /app/conf/nom_du_provider.yaml (par exemple, /app/conf/junit.yaml) :

apiVersion: opentestfactory.org/v1beta1
kind: ProviderConfig
current-context: ...
contexts:
  ...
hooks:
    - name: my hook
      events:
      - categoryPrefix: junit
        category: junit
      before:
      - run: echo hello
      after:
      - run: echo goodbye

Utiliser un fichier de définition à part et passer son chemin via la variable d'environnement {nom_du_provider}_PROVIDER_HOOKS :

JUNIT_PROVIDER_HOOKS=/app/hooks/junit_hooks.yaml

Dans ce fichier, uniquement la section hooks sera présente :

hooks:
    - name: my hook
      events:
      - categoryPrefix: junit
        category: junit
      before:
      - run: echo hello
      after:
      - run: echo goodbye

Si la variable d'environnement {nom_du_provider}_PROVIDER_HOOKS est définie, les hooks déclarés dans le fichier de configuration du provider sont ignorés.

Comment remonter des fichiers créés en cours de l'exécution vers Squash ?

Il est possible de faire remonter vers Squash des fichiers créés en cours de l'exécution, par exemple des captures d'écran. Ces fichiers seront disponibles dans la liste Rapports d'exécution.

Captures dans SquashTM

Pour ce faire, il faut mettre en place un hook.

Prenons, à titre d'exemple, l'exécution d'une suite de tests JUnit/Selenium dans un environnement Windows. Elle utilise le dépôt Git qui s'appelle seleniumtests. Une capture d'écran est faite à la fin de chaque test et sauvegardée dans le dossier target/screenShots du projet.

Pour que le hook s'applique aux exécutions Squash, il faut d'abord définir les événements (events) auxquels il est lié. Squash utilise l'action execute du provider JUnit :

hooks:
    - name: Attach screenshots to JUnit execution results
      events:
      - categoryPrefix: junit
        category: execute

Ensuite, il faut déclarer les actions qui seront lancées à la fin de l'exécution de chaque test :

hooks:
    - name: Attach screenshots to JUnit execution results
    events:
    - categoryPrefix: junit
      category: execute
    after:
    - uses: actions/get-files
      with:
        pattern: '*.png'
        warn-if-not-found: No screenshots found after execution.
      working-directory: seleniumtests/target/screenShots

Le hook utilise l'action actions/get-files pour récupérer tous les fichiers .png depuis le dossier seleniumtests/target/screenShots et les attacher aux résultats d'exécution. Si aucun fichier *.png n'est présent dans ce dossier, un avertissement sera affiché et l'exécution passera au test suivant.

Attention

Si le dossier des captures d'écran est défini à l'intérieur du projet Git, le chemin doit inclure le nom du projet.

Ce hook est a priori suffisant pour remonter les captures d'écran. Toutefois, pour éviter de joindre les captures des tests précédents à chaque test exécuté, il faut également vider le dossier screenShots de son contenu avant chaque nouvelle exécution :

hooks:
    - name: Attach screenshots to JUnit execution results
    events:
    - categoryPrefix: junit
      category: execute
    before:
    - uses: actions/delete-file
      with:
        path: '*.png'
      working-directory: seleniumtests/target/screenShots
      continue-on-error: true
    after:
    - uses: actions/get-files
      with:
        pattern: '*.png'
        warn-if-not-found: No screenshots found after execution.
      working-directory: seleniumtests/target/screenShots

Le hook utilise l'action actions/delete-file pour supprimer tous les fichiers .png dans le dossier seleniumtests/target/screenShots avant le lancement du test suivant. L'argument continue-on-error est ajouté pour ne pas interrompre l'exécution si le dossier n'est pas trouvé.

On peut, bien évidemment, modifier cet exemple en fonction du projet et l'utiliser pour transmettre, vers Squash, d'autres fichiers que des captures d'écran.

De même, le mot-clé if peut être utilisé pour restreindre la portée du hook. Pour tous les détails, se reporter à la documentation d'OpenTestFactory : chapitres Hooks et Hooks pour les plugins de providers.

Comment utiliser Maven Daemon pour l'exécution des tests ?

Qu'est-ce que Maven Daemon ?

Maven Daemon est un wrapper pour Maven qui parallélise le build des modules en utilisant plusieurs cœurs du CPU. Il s'agit d'un exécutable natif, qui consomme moins de mémoire, démarre plus rapidement et qui, en tant que daemon, n'a besoin d'être lancé qu'une seule fois. Le build devient par conséquent plus performant, ce qui permet aussi de gagner du temps sur l'exécution des tests.

Pour des tests JUnit ou Cucumber qui ne durent que quelques secondes, la durée totale d'exécution peut être réduite de 10% à 20%. Plus les tests sont longs, plus le gain sera faible.

Pour utiliser Maven Daemon au lieu de Maven, il faut d'abord l'installer dans l'environnement d'exécution.

Installer

Les différentes possibilités d'installation de Maven Daemon sont décrites en détail dans le readme du projet.

Pour une installation manuelle, il suffit de télécharger l'archive .zip le plus récent depuis apache.org et de l'extraire dans le répertoire de son choix, puis d'ajouter le chemin du bin dans le PATH. La commande mvnd --version peut alors être utilisée pour vérifier l'installation.

En même temps, c'est la commande mvn test que les providers JUnit et Cucumber de l'orchestrateur utilisent pour lancer les exécutions. Si l'on veut que les tests soient exécutés par Maven Daemon, il faut aliaser la commande mvn de sorte qu'elle pointe vers l'exécutable mvnd.

Pointer `mvn` vers `mvnd`

La procédure dépendra du système d'exploitation de l'environnement d'exécution. On présume que Java y est déjà présent et que Maven Daemon vient d'y être installé.

Windows

Renommer l'exécutable mvnd.exe (dans le bin du dossier d'installation de Maven Daemon) en mvn.exe.
Modifier les variables d'environnement système :
- MAVEN_HOME prendra comme valeur le chemin du dossier d'installation de Maven Daemon (sans bin);
- on s'assurera que la variable PATH contient le chemin relatif de l'exécutable : %MAVEN_HOME%\bin.

Variables d'environnement Windows

Pour vérifier que la substitution est effective, on peut utiliser la commande where mvn ou la commande mvn --version. La première doit afficher le chemin vers l'exécutable mvnd renommé, la seconde les informations relatives à l'installation de Maven Daemon.

Vérification mvn

Rappel

Une fois les variables d'environnement modifiées et prises en compte, il faut également relancer l'agent de l'orchestrateur dans une nouvelle invite de commandes.

Linux

Créer, dans le dossier /usr/local/bin, le fichier mvn. Ajouter, dans ce fichier, la ligne /home/user/mvnd_install_path/bin/mvnd "$@", puis rendre ce fichier exécutable.
Faire un echo $PATH et s'assurer que le chemin /usr/local/bin se situe avant le chemin de mvn. Si ce n'est pas le cas, ajouter, dans le fichier /home/user/.bashrc, la ligne suivante :
```
export PATH="/usr/local/bin:$PATH"
```
Redémarrer la session.

Pour vérifier les modifications, exécuter la commande which mvn. Cette commande doit afficher /usr/local/bin/mvn. La commande mvn --version, quant à elle, affichera les informations de Maven Daemon.

Astuce

Une alternative à la substitution du chemin de Maven est de remplacer directement son exécutable. Dans ce cas, il faut se rendre dans le dossier bin de Maven et remplacer le fichier mvn d'origine par le fichier mvn contenant la ligne /home/user/mvnd_install_path/bin/mvnd "$@". (Le plus prudent est de renommer le mvn d'origine en mvn.old.)

Comment arrêter le daemon à la fin d'un workflow ?

Sur Windows, quand un workflow est exécuté avec Maven Daemon, le daemon est lancé à l'intérieur du workspace. Par conséquent, ce dernier ne peut pas être définitivement supprimé à la fin de l'exécution. Si l'on veut éviter de polluer le dossier de l'agent de l'orchestrateur, on peut mettre en place un hook au niveau du workflow (un job hook).

Info

La mise en place des job hooks est décrite dans la documentation d'OpenTestFactory.

La première solution est d'utiliser un hook de setup pour lancer le daemon avant la création du workspace. Dans ce cas, il sera lancé dans le dossier de l'agent et le workspace pourra être supprimé à la fin de l'exécution.

hooks:
  - name: Launch Maven Daemon
    events:
    - channel: setup
    before:
    - run: mvn --version

La commande mvn --version lance un daemon avant d'afficher les informations sur la version.

On peut aussi arrêter le daemon avant la suppression du workspace pour qu'il libère le dossier respectif :

hooks:
  - name: Stop Maven Daemon
    events:
    - channel: teardown
    before:
    - run: mvn --stop