Tests de bout en bout avec Playwright

Playwright  est un framework de test pour écrire des tests fiables de bout en bout en JavaScript. L’équipe QA d’OpenMRS a contribué à standardiser Playwright sur plusieurs de nos dépôts clés.

Cela signifie que nous pouvons écrire des tests E2E pour les principaux parcours utilisateurs dans le frontend OpenMRS. Ces tests sont configurés pour s’exécuter sur les commits et les merges. Gardez-les au vert et, lorsque vous ajoutez un nouveau comportement, étendez les tests pour le couvrir. Idéalement, chaque pull request devrait inclure les tests qui prouvent que le changement fonctionne.

Pour commencer, installez Playwright:

npx playwright install

Nous recommandons:

• D’installer le plugin Playwright officiel pour VS Code  pour exécuter et déboguer vos tests.
• D’exécuter les tests via le script du dépôt, généralement yarn test-e2e, ou avec npx playwright test quand le dépôt n’a pas de script wrapper.
• De suivre les bonnes pratiques  Playwright pour garder des tests fiables et maintenables.

Rédaction de tests

Il est recommandé de lire la documentation officielle de Playwright  avant d’écrire de nouveaux cas de test. Le projet utilise l’exécuteur de test officiel Playwright et suit une structure de projet simple:

e2e
|__ commands
|   ^ Contains "commands" (simple reusable functions) that can be used in test cases/specs,
|     e.g. generate a random patient.
|__ core
|   ^ Contains code related to the test runner itself, e.g. setting up the custom fixtures.
|     You probably need to touch this infrequently.
|__ fixtures
|   ^ Contains fixtures (https://playwright.dev/docs/test-fixtures) which are used
|     to run reusable setup/teardown tasks
|__ pages
|   ^ Contains page object model classes for interacting with the frontend.
|     See https://playwright.dev/docs/test-pom for details.
|__ specs
|   ^ Contains the actual test cases/specs. New tests should be placed in this folder.
|__ support
    ^ Contains support files that are required to run E2E tests, e.g. docker-compose files.

Lorsque vous voulez écrire un nouveau scénario de test, commencez par créer une nouvelle spécification dans e2e/specs. Selon vos besoins, vous pouvez créer de nouvelles fixtures et/ou de nouveaux modèles d’objets de page. Pour voir des exemples, jetez un oeil au code existant et observez comment ces concepts fonctionnent ensemble.

Les fichiers spec utilisent souvent un style BDD. Dans ce style, nous utilisons les appels test.step de Playwright et une voix utilisateur avec le “I”. Pour plus d’informations sur la syntaxe BDD, consultez https://cucumber.io/docs/gherkin/reference/ . L’extrait ci-dessous illustre ce style:

test("Search patient by patient identifier", async ({ page, api }) => {
  // extract details from the created patient
  const openmrsIdentifier = patient.identifiers[0].display.split("=")[1].trim();
  const firstName = patient.person.display.split(" ")[0];
  const lastName = patient.person.display.split(" ")[1];
  const homePage = new HomePage(page);
 
  await test.step("Quand je visite la page d'accueil", async () => {
    await homePage.goto();
  });
 
  await test.step("Et je saisis un identifiant patient valide dans le champ de recherche", async () => {
    await homePage.searchPatient(openmrsIdentifier);
  });
 
  await test.step("Alors je ne vois que le patient avec l'identifiant saisi", async () => {
    await expect(homePage.floatingSearchResultsContainer()).toHaveText(/1 search result/);
    await expect(homePage.floatingSearchResultsContainer()).toHaveText(new RegExp(firstName));
    await expect(homePage.floatingSearchResultsContainer()).toHaveText(new RegExp(lastName));
    await expect(homePage.floatingSearchResultsContainer()).toHaveText(new RegExp(openmrsIdentifier));
  });
 
  await test.step("Quand je clique sur le patient", async () => {
    await homePage.clickOnPatientResult(firstName);
  });
 
  await test.step("Alors je devrais être sur la page du dossier patient", async () => {
    await expect(homePage.page).toHaveURL(
      `${process.env.E2E_BASE_URL}/spa/patient/${patient.uuid}/chart/Patient Summary`
    );
  });
});

Prérequis pour exécuter en local

Avant d’exécuter les tests E2E en local, assurez-vous d’avoir :

• Un backend OpenMRS en cours d’exécution (dev3 ou local).
• Un serveur de développement frontend pour le module testé.
• Les variables d’environnement requises configurées. Au minimum, définissez E2E_BASE_URL sur l’URL de base OpenMRS, par exemple http://localhost:8080/openmrs; n’incluez pas /spa.

Exécuter les tests localement

Pour exécuter les tests E2E localement, démarrez un serveur de développement pour le module frontend que vous souhaitez tester.

yarn start --sources "packages/esm-patient-conditions-app"

# 8080 est le port par défaut pour le serveur de développement
export E2E_BASE_URL=http://localhost:8080/openmrs

yarn test-e2e --headed --ui

yarn test-e2e conditions-form.spec.ts

yarn test-e2e specs/conditions specs/programs

yarn test-e2e conditions

yarn test-e2e conditions -g "Enregistrer et modifier une condition"

Données de test

Pour vous assurer que les tests disposent des données nécessaires, utilisez l’une de ces approches :

1. Utiliser l’interface utilisateur - Si le scénario implique la modification d’informations patient, créez un dossier patient via l’UI.
2. Utiliser les données de démonstration - Si le test est en lecture seule, les données de démo de la RefApp peuvent suffire. Consultez le module de données de démonstration.
3. Créer les données via l’API - Si nécessaire, générez les données avant le test via l’API.

Débogage des tests

Reportez-vous à cette documentation  pour savoir comment déboguer un test.

Artifacts de test

Lorsque les tests échouent, Playwright peut générer des traces, des captures d’écran, des vidéos et un rapport HTML selon la configuration. Dans les dépôts frontend O3 actuels, GitHub Actions téléverse généralement playwright-report/ comme artifact. Les traces et vidéos sont écrites dans les répertoires de sortie configurés dans la configuration Playwright du dépôt.

Afficher les rapports de test depuis GitHub Actions et les anciens plans Bamboo

Pour télécharger le rapport depuis une exécution GitHub Actions, ou depuis un ancien plan Bamboo qui exécute encore ces tests, procédez comme suit:

1. Allez dans la section artefact de l’action/du plan et localisez le fichier de rapport.
2. Téléchargez le fichier de rapport et décompressez-le à l’aide de l’outil de votre choix.
3. Suivez les étapes mentionnées dans ce guide sur la façon de visualiser le rapport HTML .

Le rapport vous présentera un résumé complet de vos tests, y compris des informations sur les tests qui ont réussi, échoué, ont été ignorés ou étaient défectueux. Vous pouvez explorer les détails de chaque test, y compris les erreurs ou les échecs, les enregistrements vidéo, les traces et les étapes de chaque test. Il vous suffit de cliquer sur un test pour en afficher les détails.

À faire et à ne pas faire

• Veillez à ce que tous les cas de test soient rédigés de manière claire et concise, avec des instructions étape par étape facilement compréhensibles.
• Utiliser une variété de cas de test pour couvrir tous les scénarios possibles, y compris les scénarios les plus favorables, les plus défavorables et les cas limites.
• Veiller à ce que tous les tests soient exécutés en temps voulu et de manière efficace afin de gagner du temps et d’économiser des ressources.
• Ne supposez pas qu’une fonctionnalité fonctionne simplement parce qu’elle semble fonctionner correctement. Testez-la de manière approfondie pour vous assurer que toutes ses caractéristiques et fonctionnalités fonctionnent comme prévu.
• N’ignorez pas les erreurs ou les problèmes qui surviennent pendant les tests, même s’ils semblent mineurs. Signalez-les à l’équipe de développement afin qu’ils soient traités rapidement.
• Ne sautez aucun chemin ou scénario critique. Veillez à ce que tous les scénarios soient testés de manière approfondie afin d’identifier tout problème ou défaut potentiel.

Meilleures pratiques

• Commencer les tests dès le début du processus de développement afin d’identifier et de résoudre les problèmes avant qu’ils ne deviennent plus difficiles et plus coûteux à résoudre.
• Utiliser des tests automatisés chaque fois que possible pour gagner du temps et de l’efficacité.
• Utiliser des données et des scénarios réels pour créer des cas de test précis et pertinents.
• Veiller à ce que tous les cas de test soient répétables et facilement reproductibles afin que les résultats puissent être vérifiés et testés à nouveau si nécessaire.
• Réviser et mettre à jour en permanence le plan de test pour s’assurer qu’il couvre toutes les fonctionnalités et tous les scénarios pertinents.
• Travailler en collaboration avec l’équipe O3 pour s’assurer que tout problème ou défaut est identifié et résolu rapidement.

Automatiser les tests E2E avec GitHub Actions

L’automatisation des tests de bout en bout (E2E) à l’aide des actions GitHub constitue un moyen efficace de garantir la fiabilité des modifications logicielles.

Environnement de test Dockerisé

Nos tests E2E sont exécutés dans un environnement dockerisé pour chaque pull request et chaque push vers main dans les dépôts qui définissent un workflow GitHub Actions E2E. Cette approche offre plusieurs avantages par rapport aux méthodes traditionnelles:

• Dépendance réduite au serveur Dev3: En utilisant un environnement dockerisé, les tests E2E ne dépendent pas de l’état ou de la disponibilité du serveur Dev3. Cette indépendance garantit que les tests peuvent se dérouler même si le serveur Dev3 rencontre des problèmes.

• Exécution isolée des tests: L’exécution des tests sur les PR et les commits dans des conteneurs Docker isolés élimine les conflits entre les données. Cette isolation évite les scénarios où les données de test entrent en conflit avec d’autres tests ou activités de développement en cours.

• Impact minimisé des échecs: Les échecs des tests E2E n’ont pas d’impact sur l’état ou la stabilité du serveur Dev3. Cette séparation garantit que l’environnement de développement principal n’est pas affecté par les défaillances des tests.

Optimisation du processus de test

Pour améliorer l’efficacité du processus de test E2E, nous avons mis en œuvre plusieurs méthodes d’optimisation:

1. Images Docker pré-remplies: Les images Docker du backend et de la base de données utilisées pour les tests E2E automatisés sont pré-remplies avec les données et les configurations nécessaires. Il n’est donc pas nécessaire de générer des données lors de la configuration initiale de l’environnement de test. Par conséquent, le temps de configuration est considérablement réduit, ce qui permet une création rapide de l’instance de test.

2. Frontend léger et dynamique: Pour exécuter les tests automatisés, le workflow GitHub Actions construit une image frontend légère à partir d’un spa-assemble-config.json généré. Cette configuration empaquette les apps du dépôt courant et ajoute les apps de base nécessaires au script de support E2E de ce dépôt, comme la navigation principale, la page d’accueil, le dossier patient ou le bandeau patient.

Les images Docker pré-remplies du backend et de la base de données, ainsi que l’image frontale légère construite dynamiquement, sont combinées dans la même pile docker-compose et utilisées pour configurer l’environnement de test E2E.

Détails supplémentaires de la mise en œuvre

Génération d’images Docker: Les workflows GitHub Actions E2E actuels consomment les images pré-remplies openmrs/openmrs-reference-application-3-backend:nightly-with-data et openmrs/openmrs-reference-application-3-db:nightly-with-data dans leur stack docker-compose. Ces images sont produites en dehors du dépôt de module frontend, historiquement via une étape Bamboo dédiée dans le job REFAPP-D3X . Plus de détails sont disponibles ici .

Dépannage

Si vous ne pouvez pas déboguer les tests en mode UI  parce que votre serveur web local se recharge en raison de modifications de fichiers statiques, utilisez le Playwright Inspector  à la place. Exécutez la commande suivante:

yarn test-e2e --headed --debug

Cette approche devrait éviter les problèmes causés par le file watching du bundler et les modifications de fichiers statiques.

Si votre serveur de dev continue à se recharger en boucle parce que Playwright écrit des artifacts dans un dossier surveillé, une solution locale courante consiste à définir outputDir en dehors du module frontend dans playwright.config.ts. C’est un problème connu lié au file watching. Pensez à annuler ce changement avant de committer.

// Solution locale uniquement (ne pas committer)
outputDir: "../e2e/output",