Récupération d’un plan d’exécution Squash TM depuis un workflow

Squash vous donne la possibilité d'insérer dans un pipeline CI/CD une étape pour récupérer et exécuter un plan de test automatisé défini dans Squash TM à l'aide un workflow écrit en YAML ou JSON. Dans le cas de Jenkins, la configuration de cette étape peut être simplifiée par l'utilisation d'un plugin, voir la page correspondante de ce guide.
Vous pouvez retrouver plus d’informations sur la rédaction d’un workflow dans la documentation de l'OpenTestFactory Orchestrator.

Focus

Pour le bon fonctionnement de cette fonctionnalité, les plugins Test Plan Retriever et Result Publisher doivent être installés sur l'instance Squash TM ciblée.

Prérequis

Un utilisateur appartenant au groupe Serveur d’automatisation de tests doit exister dans Squash TM.

Intégration de l’étape de récupération d’un plan d’exécution Squash TM dans un workflow

Dans Squash TM, le plan d’exécution, itération ou suite de tests, doit contenir au moins un ITPI (Iteration Test Plan Item, voir le glossaire Squash TM) lié à un cas de test automatisé suivant les instructions décrites ici.

Pour récupérer ce plan d’exécution dans un workflow, il faut faire appel à l’action generator correspondante.

Voici un exemple simple d'un tel workflow au format JSON :

{
    "apiVersion": "opentestfactory.org/v1alpha1",
    "kind": "Workflow",
    "metadata": {
        "name": "Simple Workflow"
    },
    "defaults": {
        "runs-on":"ssh"
    },
    "jobs": {
        "explicitJob": {
            "runs-on":"ssh",
            "generator":"tm.squashtest.org/tm.generator@v1",
            "with": {
                "testPlanUuid":"1e2ae123-6b67-44b2-b229-274ea17ad489",
                "testPlanType":"Iteration",
                "squashTMUrl":"https://squashtm.example.com/squash",
                "squashTMAutomatedServerLogin":"tfserver",
                "squashTMAutomatedServerPassword":"tfserver",
                "technologyLabels":{
                    "ranorex": ["windows","ranorex"],
                    "robotframework": ["linux","robotframework"],
                    "junit": ["linux","junit"]
                }
            }
        }
    }
}

Un step generator Squash TM doit contenir les paramètres suivants :

testPlanType : Correspond au type du plan de test à récupérer dans Squash TM. Seules les valeurs Iteration et TestSuite sont acceptées.
testPlanUuid : Correspond à l’UUID (Universally Unique IDentifier, voir la documentation Squash TM) du plan de test souhaité. Celui-ci peut être récupéré dans le bloc Information de l’itération ou de la suite de tests souhaitée dans Squash TM.
squashTMUrl : URL du Squash TM à viser.
squashTMAutomatedServerLogin : Nom de l’utilisateur du groupe Serveur d’automatisation de tests à utiliser dans Squash TM.
squashTMAutomatedServerPassword : Mot de passe de l’utilisateur du groupe Serveur d’automatisation de tests à utiliser dans Squash TM.

Champs Optionnels :

tagLabel : Spécifique à la version Ultimate - Correspond au nom du champ personnalisé de type tag sur lequel on souhaite filtrer les cas de test à récupérer.
Il n’est pas possible d’en spécifier plusieurs.
tagValue : Spécifique à la version Ultimate - Correspond à la valeur du champ personnalisé de type tag sur lequel on souhaite filtrer les cas de test à récupérer.
Il est possible d’indiquer plusieurs valeurs séparées par des | (exemple valeur1|valeur2). Il faut au moins l’une des valeurs soit associée au cas de test pour que celui-ci soit pris en compte.

Focus

Si l’un des deux champs tagLabel ou tagValue est présent, alors l’autre champ doit également être renseigné.

technologyLabels : À utiliser notamment si vous récupérez un plan d'exécution contenant des tests devant s'exécuter sur des environnements différents.
Il permet de spécifier pour chaque framework d'automatisation les étiquettes de l'environnement d'exécution à cibler.
Celles-ci seront ajoutées aux étiquettes du runs-on du job Generator.
Pour une technologie donnée, les étiquettes se précisent en ajoutant une entrée à la liste du champ sous la forme "préfixe de la technologie": ["etiquette1", "etiquette2"].

Info

Par défaut, les jobs créés par le Generator suite à la récupération d'un plan d'exécution se voient attribués une étiquette correspondant au préfixe de la technologie de test (nom de la technologie en minuscule sans espace, par exemple "robotframework" pour Robot Framework) en plus de celles renseignées dans le runs-on du job generator.

Ordre d'exécution des tests

Le seul ordre assuré par Squash est que, pour un dépôt Git donné dans une itération/suite de tests donnée, les tests seront exécutés dans l'ordre défini dans Squash TM.
Si une itération/suite de tests contient des tests automatisés appartenant à plusieurs dépôts Git, l'ordre d'exécution des tests d'un dépôt par rapport à l'exécution des tests d'un autre dépôt est indéfini.
Si plusieurs itérations/suites de tests sont lancées depuis Squash TM (resp. le pipeline CI/CD), l'ordre d'exécution des tests d'une itération/suite par rapport à l'exécution des tests d'une autre itération/suite est indéfini. (Sauf dans le cas simpliste où un environnement d'exécution adéquat est disponible et la première suite/itération a pu démarrer avant que l'utilisateur Squash TM – resp. le pipeline CI/CD – en lance une autre.)

Utilisation avec l'environnement d'exécution `inception` de l'orchestrateur

OpenTestFactory, et de fait Squash, propose un environnement d'exécution spécial nommé inception qui permet un mode d'utilisation alternatif des jobs de type generator.

À quoi sert l'environnement `inception` ?

Le processus normal d'exécution d'un job generator est d'aller récupérer un plan d'exécution depuis une instance de Squash TM puis d'aller exécuter les tests automatisés de ce plan sur les environnements d'exécution dédiés. Lorsque l'environnement d'exécution inception est utilisé pour le job generator, il n'y a pas de tests exécutés suite à la récupération du plan d'exécution. À la place, il y a directement l'étape de remontée d'information vers Squash TM basée sur un ensemble de rapports transmis à l'orchestrateur en amont.

Comment utiliser l'environnement `inception` au sein d'un workflow

Voici un exemple de workflow au format YAML utilisant l'environnement d'exécution inception et allant récupérer un plan d'exécution Squash TM.

metadata:
  name: Test Inception
resources:
  files:
  - report1
  - report2
  - report3
jobs:
  prepare:
    runs-on: inception
    steps:
    - uses: actions/prepare-inception@v1
      with:
        report.html: ${{ resources.files.report1 }}
        output.xml: ${{ resources.files.report2 }}
        log.html: ${{ resources.files.report3 }}
  robot:
    runs-on: inception
    needs: [prepare]
    generator: tm.squashtest.org/tm.generator@v1
    with:
      squashTMUrl: https://squashtm.example.com/squash
      squashTMAutomatedServerLogin: ${{ variables.SQUASH_USER }}
      squashTMAutomatedServerPassword: ${{ variables.SQUASH_PASSWORD }}
      testPlanUuid: 1e2ae123-6b67-44b2-b229-274ea17ad489
      testPlanType: Iteration

Plusieurs différences sont à noter par rapport au workflow présenté à la section précédente :

La section files dans la partie resources : elle permet de lister les rapports fournis en entrée à l'orchestrateur. C'est à partir de ces rapports que seront extraites les informations remontées à Squash TM.
Un job de préparation, intitulé prepare dans cet exemple : il utilise l'action provider actions/prepare-inception@v1 et permet d'indiquer à quel rapport normalement généré par le test correspond chaque rapport renseigné dans le bloc files.
La liste des rapports supportés par Squash Orchestrator est indiquée dans la page correspondant à chaque technologie de test :
- Agilitest💎
- Cucumber JVM
- Cypress
- JUnit
- Katalon💎
- Postman
- Ranorex💎
- Robot Framework
- SKF
- SoapUI
- UFT💎💎
Le premier rapport de la liste (qui est le rapport Surefire pour la plupart des technologies de test) doit être présent pour que l'orchestrateur puisse déterminer le résultat du test.
Le job generator : il est très semblable à la version de la section précédente à deux points près :
- Il utilise l'environnement inception dans son champ runs-on
- Il précise que le job de préparation est un pré-requis pour son exécution via la ligne needs: [prepare]

Un tel workflow peut être exécuté via l'appel suivant :

BashCMDPowerShell

curl -X POST \
     -H "Authorization: Bearer ${TOKEN}" \
     -F workflow=@Squashfile \
     -F report1=@report1.html \
     -F report2=@report2.xml \
     -F report3=@report3.xml \
     -F variables="SQUASH_USER=${USER}\nSQUASH_PASSWORD=${PASSWD}" \
     http://orchestrator.example.com/workflows

curl -X POST ^
     -H "Authorization: Bearer %TOKEN%" ^
     -F workflow=@Squashfile ^
     -F report1=@report1.html ^
     -F report2=@report2.xml ^
     -F report3=@report3.xml ^
     -F variables="SQUASH_USER=%USER%\nSQUASH_PASSWORD=%PASSWD%" ^
     http://orchestrator.example.com/workflows

curl -X POST `
     -H "Authorization: Bearer $Env:TOKEN" `
     -F workflow=@Squashfile `
     -F report1=@report1.html `
     -F report2=@report2.xml `
     -F report3=@report3.xml `
     -F variables="SQUASH_USER=$Env:USER\nSQUASH_PASSWORD=$Env:PASSWD" `
     http://orchestrator.example.com/workflows

Il est à noter dans cet appel le passage en paramètre des rapports renseignés dans le workflow.

Un workflow exploitant l'environnement d'exécution inception peut aussi être déclenché depuis un pipeline Jenkins grâce au step proposé par le plugin Jenkins.

Paramètres Squash TM exploitables dans un test automatisé

En exécutant un workflow avec récupération d’un plan d’exécution Squash TM, ce dernier transmet différentes informations sur les éléments du plan d'exécution qu’il est possible d’exploiter dans un cas de test.

Les technologies suivantes supportent l'exploitation des paramètres Squash TM :

Chacune de ces pages décrit les paramètres récupérables par le script de test et comment les récupérer.

Remontée d’informations vers Squash TM en fin d’exécution

Les résultats et les rapports des tests exécutés sont remontés et accessibles dans Squash TM de la même façon que pour une exécution lancée depuis ce dernier, voir ce paragraphe.