7.5 KiB
7.5 KiB
DOC-Gauntlet : Gauntlet du moteur 5.8 et embarquement du cadre d'automatisation
Rédigé le 2026-10-15 par un sous-agent. Source de vérité : code local du moteur 5.8.3 (changelist 58210709). Date de publication : inconnue. Niveaux : établi (fichier:ligne), estimé, incertain.
Identité et chemins
- URL doc 5.8 (non rouverte ici, voir R3-11, R3-12) : https://dev.epicgames.com/documentation/en-us/unreal-engine/running-gauntlet-tests-in-unreal-engine ; bandeau 5.8, date inconnue.
- Source local : D:\Game\Launcher\Engine\UE_5.8\Engine\Source\Programs\AutomationTool\Gauntlet\ (dossiers Editor, Framework, Platform, SelfTest, Unreal ; projet Gauntlet.Automation.csproj). Tests Unreal : ...\Gauntlet\Unreal\Automation\UE.Automation.cs (EditorAutomation, TargetAutomation), ...\Unreal\Editor\EditorTests.cs, ...\Unreal\Engine\UnrealTests.cs, ...\Unreal\RunUnreal.cs.
- Autres tests de nœud présents (fichiers UE.*.cs, établi par listage) : BootTest, CookByTheBook et variantes, CookOnTheFly, ErrorTest, Networking, PLMTest, ZenLoaderTest, ZenStreaming, InstallOnly.
Cadre d'automatisation embarqué en build empaquetée : réponse (établi)
C'est la lacune ouverte de R3. Règles lues dans le code local :
- Définition : AutomationTest.h:63-65 définit WITH_AUTOMATION_TESTS = (WITH_DEV_AUTOMATION_TESTS ou WITH_PERF_AUTOMATION_TESTS) si non défini.
- Valeur par cible : UEBuildTarget.cs:6316 : bCompileDevTests vaut vrai sauf si la configuration est Test ou Shipping ; bCompilePerfTests = bCompileDevTests (:6317). Les définitions WITH_DEV_AUTOMATION_TESTS et WITH_PERF_AUTOMATION_TESTS sont ajoutées aux lignes 6331-6332. Même règle dans ReadOnlyTargetRules.cs:722-740 (propriété WithAutomationTests).
- Surcharges dans le .Target.cs : bForceCompileDevelopmentAutomationTests (TargetRules.cs:1726 ; appliqué UEBuildTarget.cs:6318-6321), bForceCompilePerformanceAutomationTests (TargetRules.cs:1731 ; appliqué :6322-6325), bForceDisableAutomationTests (TargetRules.cs:1736 ; appliqué :6326-6329, prioritaire sur les deux autres).
- Résultat : Development (et Debug, DebugGame) = tests compilés (1). Test et Shipping = non compilés (0), sauf bForceCompile... à vrai. Shipping avec les drapeaux Force est techniquement possible par ces lignes (non essayé).
- Le travailleur d'automatisation (module AutomationWorker) est un autre define : WITH_AUTOMATION_WORKER vaut !UE_BUILD_SHIPPING (Build.h:127 ; le commentaire de Build.h:124-125 dit qu'il est actif en Test pour les tests de perf sur appareil). Il est chargé dans LaunchEngineLoop.cpp:240 (include), :4911 (LoadModule "AutomationWorker"), :6036 (tick). La ligne de commentaire ~4916 du même fichier précise qu'on peut lancer des tests en local hors éditeur (exemple : profilage en Test).
- Conséquence pour LifePlay : une build empaquetée Development contient le registre de tests (WITH_AUTOMATION_TESTS=1) et le travailleur ; une build Test contient le travailleur mais PAS les tests déclarés sous WITH_AUTOMATION_TESTS ; une build Shipping ne contient ni l'un ni l'autre. Les tests propres au projet dépendent aussi du garde (#if) du module qui les déclare (estimé, non lu dans le code LifePlay).
Tests Gauntlet UE.EditorAutomation et UE.TargetAutomation (établi)
- EditorAutomation : UE.Automation.cs:390 ; exemple de commentaire (:387-389) RunUnreal -test=UE.EditorAutomation -RunTest="Group:Animation".
- TargetAutomation : UE.Automation.cs:423-460. Elle EXIGE un rôle Editor qui héberge la session (« Target tests require an editor which hosts the process »), ajoute -NoWatchdog -stdout -FORCELOGFLUSH -CrashForUAT et, si non attendu (non Attended), nullrhi pour l'éditeur, et exige aussi un rôle Client (la cible).
- Côté client, la ligne de commande générée est -sessionid= -messaging -TcpMessagingConnect=<IP hôte>:6666 -ExecCmds="Automation List;" (:272). Côté éditeur : -ExecCmds="Automation StartRemoteSession ; RunTest ;" -TcpMessagingListen=:6666 -multihome= (:276). Dans le cas éditeur seul : -ExecCmds="Automation RunTest ;" (:254). En non attendu, ajoute Quit; et -unattended (autour de :236-240). Donc les tests ne sont pas lancés par le client empaqueté lui-même : l'éditeur pilote le client à distance, et le jeu empaqueté doit contenir le travailleur et les tests (règle ci-dessus).
Paramètres de ligne de commande de Gauntlet (AutoParam, AutomationTestConfig, UE.Automation.cs, établi)
| Paramètre | Ligne | Rôle (résumé) |
|---|---|---|
| RunTest | 93 | obligatoire (erreur AutomationException si vide, :168-171) ; nom, Group:nom ou Project |
| ReportExportPath | 99 | dossier d'export du rapport |
| ReportURL | 105 | URL du rapport |
| TelemetryDirectory | 111 | dossier de télémétrie |
| SimpleHordeReport | 117 | rapport Horde simplifié |
| ResumeOnCriticalFailure | 123 | reprise après échec critique ; ajoute -ResumeRunTest à la ligne de commande (:178) |
| VerifyDDC, DDC | 129, 135 | contrôle et choix du DDC |
| LogIdleTimeout | 141 | délai de silence du journal (défaut 30 min, en secondes) |
| EnableStereoTestVariants | 147 | variantes stéréo des tests image |
| RHI, RHIValidation, PreferNvidia, RayTracing, StompMalloc, D3DDebug, AttachRenderDoc | 26, 57, 63, 69, 75, 81, 87 | options graphiques et de débogage |
EngineTest (Unreal\Engine\UnrealTests.cs) : paramètre MaxDuration (défaut 3600, :109), option AllowZeroTestResults (:268). Les paramètres de RunUnreal (-build, -platform, -configuration, -test) sont décrits dans les pages Epic (R3-12) ; ils n'ont pas été relus dans RunUnreal.cs.
Écarts doc / code local
| Point | Doc ou BC | Constat local | Niveau |
|---|---|---|---|
| Embarquement du cadre | R3 lacunes : règle inconnue ; nom WITH_AUTOMATION_TESTS « de mémoire » | Règle établie : UEBuildTarget.cs:6316-6332 (Development oui, Test et Shipping non, surcharges Force) | établi |
| TargetAutomation | R3-12 : exécute le cadre « sur un client empaqueté » | Le code exige en plus un éditeur hôte (rôle Editor) qui pilote le client par TcpMessaging ; LifePlay devra disposer d'un éditeur 5.8 sur le poste du banc | établi |
| -ExecCmds sur le binaire empaqueté | R3 lacunes : aucun exemple Epic | Gauntlet met -ExecCmds="Automation List;" côté client et pilote les tests depuis l'éditeur (UE.Automation.cs:272, :276) | établi |
| -ReportExportPath | R3-02 (-ReportExportPath) vs tessl (-ReportOutputPath) | Le paramètre Gauntlet est ReportExportPath (UE.Automation.cs:99) ; ReportOutputPath absent de cette liste | établi |
| -ResumeOnCriticalFailure | R3-13 : sauvegarde un JSON et reprend jusqu'à trois fois | Le code ajoute -ResumeRunTest (:178) ; le nombre de reprises n'a pas été relu | partiel |
| -NullRHI | R3-10 estimé | Gauntlet l'applique à l'éditeur en non attendu (TargetAutomation) ; le client n'est pas en nullrhi par ce code | établi |
| Gauntlet en 5.8 | R3-101 : pas de mention dans les notes 5.8 | Code présent et complet en 5.8.3 (dossier Gauntlet, RunUnreal, tests UE.*) | établi |
Non établi
- Date de la doc ; comportement d'une cible Test avec bForceCompile... (non compilé ici).
- Fichier Target.cs de LifePlay (non lu) : valeur actuelle des drapeaux Force et module de tests existant.
- Format du rapport JSON de Gauntlet (R3-13) et contenu de ReportExportPath.
- Paramètres de RunUnreal.cs (-build, -platform, -configuration) non relus ; support DX12 ou autre RHI sur le poste.
- Automation Driver, Screenshot Comparison, CQTest hors PIE en build empaquetée : toujours silence (R3).
- Nombre exact de reprises de ResumeOnCriticalFailure.