LifePlay-Revival/Docs/Migration/etat/OPT/BC/BC-R3.md

# BC-R3 : tests automatisés UE5 (Automation Test Framework, CQTest, Low Level Tests, Functional Tests, Gauntlet, Automation Driver, ligne de commande, captures)

Date 2026-10-15 ; auteur sous-agent Sonnet OPT0-R ; 16 entrées : 14 établi, 2 estimé, 0 non vérifié. R10 : +1 entrée(s) établi (R3-101…), voir BC-R10-SOURCES.md.

Lecture rapide pour décider l'ambition d'un banc d'essai automatique :
- Éditeur seulement (documenté) : exécution via UnrealEditor-Cmd avec -ExecCmds, CQTest PIE/réseau, Screenshot Comparison (comparaison dans Session Frontend), Test Automation window.
- Build empaquetée (documenté) : uniquement via Gauntlet UE.TargetAutomation (RunUAT RunUnreal) ou Unreal Frontend ; les pages Epic lues ne disent rien de plus sur les types de tests supportés, ni sur le define de compilation qui embarque le framework (voir Lacunes).
- Aucune page Epic lue ne documente la comparaison de captures ni l'Automation Driver en build empaquetée.

| id | affirmation (1-2 phrases, sans copie de texte) | source (URL, date, version UE) | niveau (établi / estimé / non vérifié) | application à LifePlay (système ou fichier) | action proposée | skill de destination |
|---|---|---|---|---|---|---|
| R3-01 | Les tests se lancent en ligne de commande en ajoutant -ExecCmds à l'exécutable éditeur ou client : Automation RunTest A+B;Quit pour plusieurs tests, un chemin de section pour un ensemble, Group:nom pour un groupe. Le Quit final ferme le programme. | https://dev.epicgames.com/documentation/en-us/unreal-engine/run-automation-tests-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Script de lancement du banc d'essai (Tools/, PowerShell) | Écrire un lanceur qui compose -ExecCmds et sort avec Quit | lp-autotest |
| R3-02 | -ReportExportPath enregistre les résultats en JSON avec des fichiers HTML associés ; -ResumeRunTest reprend au premier test non exécuté, les tests en cours étant comptés en échec. Utile après un plantage. | https://dev.epicgames.com/documentation/en-us/unreal-engine/run-automation-tests-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Rapports de tests sous Saved/ ou etat/ | Prévoir -ReportExportPath et un analyseur du JSON ; tester -ResumeRunTest sur un plantage provoqué | lp-autotest |
| R3-03 | Les groupes de tests se définissent dans DefaultEngine.ini par +Groups avec des filtres (Contains / MatchFromStart) ; +ExcludeTest exclut un test avec raison, éventuellement par RHI ; les exclus sont rapportés « Skipped ». | https://dev.epicgames.com/documentation/en-us/unreal-engine/configure-automation-tests-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Config projet (DefaultEngine.ini), groupes type PreSubmit / Nuit | Définir des groupes (rapide / lent / rendu) et une liste d'exclusions motivée | lp-autotest |
| R3-04 | Le cadre distingue des types de tests : unitaire, fonctionnalité, fumée (visés sous 1 s, lancés par défaut), contenu intensif (ex. chargement de toutes les cartes) et comparaison de captures. Les tests placés dans des plugins peuvent être inclus dans les builds empaquetées à la compilation. | https://dev.epicgames.com/documentation/en-us/unreal-engine/automation-test-framework-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Plugin LPSandbox / modules de test | Placer les tests dans un module ou plugin dédié, inclus ou non selon la cible | lp-autotest |
| R3-05 | Automation Spec (BDD) : DEFINE_SPEC ou BEGIN/END_DEFINE_SPEC, Define() avec Describe / It / LatentIt (rappel Done), BeforeEach / AfterEach et variantes latentes, préfixe x pour désactiver. Les exemples utilisent ProductFilter ou SmokeFilter avec ApplicationContextMask. | https://dev.epicgames.com/documentation/en-us/unreal-engine/automation-spec-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Tests C++ des modules LP* (logique, sérialisation) | Écrire les tests de logique en Spec ; ApplicationContextMask vise éditeur et jeu | lp-autotest |
| R3-06 | CQTest est un module livré avec le moteur (dépendance « CQTest » dans Build.cs) : macros TEST, TEST_CLASS avec BEFORE_EACH / AFTER_EACH et TEST_METHOD, actions latentes (FWaitUntil, FExecute), ActorTestSpawner (monde minimal) et MapTestSpawner (carte temporaire ou donnée). L'état des membres est réinitialisé entre tests. | https://dev.epicgames.com/documentation/en-us/unreal-engine/cqtest-test-framework-for-unreal-engine ; date inconnue ; UE 5.8 | établi | Tests de gameplay C++, Build.cs des modules de test | Ajouter CQTest aux dépendances du module de test ; préférer TEST_CLASS pour les tests avec état | lp-autotest |
| R3-07 | En CQTest, PIENetworkComponent (serveur + client PIE) et CQTestBlueprintHelper exigent EAutomationTestFlags::EditorContext : éditeur seulement. CQTestBlueprintHelper est déprécié au profit de CQTestAssetHelper et FAssetBuilder. | https://dev.epicgames.com/documentation/en-us/unreal-engine/cqtest-test-framework-for-unreal-engine ; date inconnue ; UE 5.8 | établi | Tests réseau / Blueprints | Ne pas compter sur ces aides pour une cible empaquetée ; éviter CQTestBlueprintHelper dans le nouveau code | lp-autotest |
| R3-08 | Les Functional Tests se montent en plaçant un Functional Test Actor (classe C++ ou Blueprint) dans une carte dédiée ; le test pilote le niveau. Cycle de vie rapporté par un guide : PrepareTest / IsReady / StartTest / FinishTest, FinishTest obligatoire sinon attente jusqu'au délai. | https://dev.epicgames.com/documentation/en-us/unreal-engine/functional-testing-in-unreal-engine (établi, partiel) ; https://dev.to/gamedevtoollab/testing-in-unreal-engine-5-cqtest-automation-spec-functional-tests-and-ci-3776 (guide, 31 juillet, année non visible, fondé sur la doc 5.8) | établi | Cartes de test Blueprint (héritage UE4), cartes courtes dédiées | Créer de petites cartes de test par scénario avec un Functional Test Actor Blueprint | lp-autotest |
| R3-09 | Un guide en ligne de commande donne le motif éditeur : UnrealEditor-Cmd projet [carte] -Unattended -NoSplash [-NullRHI] -ExecCmds="Automation RunTest chemin;Quit" -ReportExportPath=dossier. -Unattended supprime les dialogues bloquants. Le guide ne mentionne pas -NoSound. | https://dev.to/gamedevtoollab/testing-in-unreal-engine-5-cqtest-automation-spec-functional-tests-and-ci-3776 ; 31 juillet, année inconnue ; UE 5.8 | estimé | Lanceur du banc d'essai | Adopter ce motif pour le niveau « éditeur sans rendu » ; tester -NoSound localement | lp-autotest |
| R3-10 | -NullRHI convient aux tests sans rendu, mais doit être retiré pour captures, Slate, viewports, matériaux, contrôles GPU et tests marqués NonNullRHI ; il faut séparer les tâches avec et sans rendu. Source unique, non confirmée par Epic. | https://dev.to/gamedevtoollab/testing-in-unreal-engine-5-cqtest-automation-spec-functional-tests-and-ci-3776 ; 31 juillet, année inconnue ; UE 5.8 | estimé | Banc d'essai : deux profils (sans rendu / avec rendu, GPU requis) | Prévoir deux profils de lancement et vérifier sur le poste que les captures fonctionnent hors NullRHI | lp-autotest |
| R3-11 | Gauntlet pilote des sessions (tous les processus nécessaires à une partie : clients, serveur) sans exiger de code de test dans le jeu ; un plugin optionnel fournit TestController pour piloter une instance. Il est conçu pour plusieurs plateformes. | https://dev.epicgames.com/documentation/en-us/unreal-engine/gauntlet-automation-framework-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Niveau « build empaquetée » du banc d'essai | Réserver Gauntlet aux scénarios empaquetés / multi-processus | lp-autotest |
| R3-12 | RunUAT RunUnreal -test=UE.TargetAutomation exécute le cadre d'automatisation sur un client empaqueté (-build=chemin du jeu empaqueté, -runtest=nom) ; UE.EditorAutomation fait de même pour l'éditeur (-build=editor). Exemple Lyra : -platform=Win64 -configuration=Development -build=local, build produite par BuildCookRun -build -cook -pak -stage dans Saved/StagedBuilds. | https://dev.epicgames.com/documentation/en-us/unreal-engine/running-gauntlet-tests-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Chaîne de packaging LifePlay (BuildCookRun) + banc d'essai | Prototyper un RunUnreal TargetAutomation sur une build Development empaquetée de test | lp-autotest |
| R3-13 | Gauntlet : -ResumeOnCriticalFailure sauvegarde un JSON avant le début et reprend jusqu'à trois fois ; un rapport récapitulatif est créé, mais son format n'est pas documenté. Win64 est la seule plateforme montrée ; consoles et mobile demandent d'implémenter les interfaces ITargetDevice et autres. | https://dev.epicgames.com/documentation/en-us/unreal-engine/running-gauntlet-tests-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Lecture des rapports du banc d'essai | Ne pas supposer de format de rapport Gauntlet : lire un rapport réel avant d'écrire l'analyseur | lp-autotest |
| R3-14 | Automation Driver simule clavier et souris (déplacement, clic, saisie, défilement, glisser-déposer) via IAutomationDriverModule (Enable / CreateDriver), au niveau plateforme donc sans dépendre de Slate. Les widgets se repèrent par FDriverMetaData::Id, chemin ou position ; l'API synchrone ne doit pas tourner sur le GameThread ; délai implicite 3 s ; l'usage conseillé est avec Automation Spec. La page ne dit pas s'il fonctionne en build empaquetée. | https://dev.epicgames.com/documentation/en-us/unreal-engine/automation-driver-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Tests d'interface UMG / menus | Étiqueter les widgets clés avec un Id ; tester l'Automation Driver d'abord dans l'éditeur | lp-autotest |
| R3-15 | Screenshot Comparison : une capture prise par un Functional Screenshot Test (ou depuis un Functional Test Blueprint) est comparée à une image de référence approuvée ; les résultats se consultent dans le navigateur Screenshot Comparison de Session Frontend. Tolérances Zéro / Basse (défaut) / Moyenne / Haute / Personnalisée, options d'ignorer l'anticrénelage ou les couleurs. Captures par défaut dans Saved/Automation/Comparisons ; les rapports ne sont pas nettoyés seuls. La page décrit l'usage éditeur et ne traite ni ligne de commande ni build empaquetée. | https://dev.epicgames.com/documentation/en-us/unreal-engine/screenshot-comparison-tool-in-unreal-engine ; date inconnue ; UE 5.8 | établi | Tests visuels de non-régression (rendu, UI) | Prévoir un dossier de références, supprimer les rapports avant chaque passage ; valider d'abord la stabilité sur le même GPU | lp-autotest |
| R3-16 | Low Level Tests : tests Catch2 modulaires et légers, construits comme exécutable à part via une cible dérivée de TestTargetRules (UBT cible Development Win64, exécutable sous Binaries/plateforme/nom de cible) ou via BuildGraph (LowLevelTests.xml). Options d'exécution : --log, --mt, --timeout, --extra-args, et -r xml pour Catch2. Sans éditeur ni carte : adaptés au code C++ pur, pas à l'héritage Blueprint. | https://dev.epicgames.com/documentation/en-us/unreal-engine/build-and-run-low-level-tests-in-unreal-engine ; https://dev.epicgames.com/documentation/unreal-engine/write-low-level-tests-in-unreal-engine (résultat de recherche seulement, non ouvert) ; date inconnue ; UE 5.8 | établi | Modules C++ purs (LPCoupleSimCore, compat chaînes) | Envisager LLT pour le noyau C++ sans dépendance moteur lourde (au-delà de LPTestStringCompat) | lp-validate |
| R3-101 | Les notes 5.6 ajoutent à Gauntlet des appels RPC asynchrones  ; le mot Gauntlet n'apparaît pas dans les notes 5.8 (aucun retrait annoncé). | https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-6-release-notes?application_version=5.6 / date inconnue (lue 2026-10-15) / UE 5.6 | établi | Banc d'essai par paliers : Gauntlet est mûr depuis 5.6, sans retrait annoncé en 5.8. | Garder Gauntlet comme second palier de l'axe B. | lp-autotest |

## Lacunes et doutes

- Define de compilation : je n'ai trouvé dans aucune page lue la règle exacte qui embarque (ou non) le cadre d'automatisation dans une build empaquetée Development / Test / Shipping (le nom WITH_AUTOMATION_TESTS vient de la mémoire et d'un résultat de recherche sans détail). À vérifier dans le code source du moteur 5.8 avant toute promesse. Une page tierce prétend que -ExecCmds exige une console et que Shipping la retire : non confirmé, donc non retenu comme entrée.
- Aucun exemple Epic de -ExecCmds="Automation RunTests …" directement sur le binaire du jeu empaqueté ; seul le chemin Gauntlet UE.TargetAutomation et le Unreal Frontend sont documentés. Un message de forum cité par un résumé de recherche évoque -ClientExecCmds avec RunUnreal : non ouvert, non retenu.
- Statut empaqueté non documenté pour : Automation Driver, Screenshot Comparison, Functional Tests (cartes), CQTest hors PIE. Les pages Epic lues sont muettes, ce qui ne prouve ni oui ni non.
- Nom du paramètre de rapport : Epic documente -ReportExportPath ; une page tierce (https://tessl.io/registry/testland/unreal-automation-system/files/references/running-and-reporting.md, date inconnue, indique UE 5.4 en exemple) écrit -ReportOutputPath, et ajoute -testexit et -nopause. Source contradictoire et non vérifiée : tenir -ReportExportPath pour la référence jusqu'à essai. Aucun code de sortie commun documenté ; ce même guide conseille de lire le JSON (états Fail / NotRun) plutôt que le code de sortie.
- -NullRHI : aucune page Epic lue n'en décrit l'effet sur les tests ; l'avis de R3-10 repose sur un guide unique. Un fil de forum trouvé sur USE_NULL_RHI (avril 2026) concerne un échec de packaging Android, sans lien utile.
- Aucune date de publication disponible sur les pages de documentation Epic (toutes marquées UE 5.8 par leur titre). Les notes de version 5.6 à 5.8 sur les tests n'ont pas été consultées (recherche bornée) : l'évolution 5.6 vers 5.8 des tests n'est pas couverte.
- CQTest : macros lues sur la page 5.8 ; je n'ai pas confirmé leur présence identique en 5.6 / 5.7. Page Low Level Tests principale vide à l'extraction : le contenu vient de la page « build and run » et des résumés de recherche.
- Non couverts : -NoSound et -game dans ce contexte, exécution de Screenshot Comparison en ligne de commande, rapports HTML (serveur de rapports).