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).