dsh-maestro-progress — suivi des tests Maestro dans le Harness

Plugin hors-dépôt pour DeepSeek Harness : une vue « Maestro » dans le Harness Web qui suit l'avancement d'une suite de tests Maestro en direct, flow par flow et étape par étape, et permet de composer des scénarios de bout en bout à partir des flows existants.

Les deux moitiés vivent dans ce paquet, sans build : index.js (hôte) lance la suite, suit le journal de debug de Maestro et sert une petite API HTTP ; client.js (navigateur) enregistre l'icône de la barre latérale, le panneau principal et l'onglet de la barre latérale droite. Le panneau interroge l'API en polling toutes les 1,5 s.

Prérequis

• Harness ≥ 0.2.0-rc.1 (testé sur 0.2.1-rc.5).
• Maestro CLI 2.x (maestro --version).
• Un projet contenant .maestro/flows/*.yaml (et éventuellement .maestro/subflows/*.yaml).
• Pour les scénarios composés : un simulateur iOS démarré ou un émulateur Android connecté, et le serveur Metro du projet (port 8084 par défaut, 8083 restant le serveur de dev).

Installation

Le paquet s'installe depuis ce dépôt GitHub (dsh étant le CLI fourni par l'application, ou le CLI npm global) :

# Application de bureau (profil desktop) : quitter complètement l'application
# avant l'installation, puis la relancer.
dsh plugin --profile desktop add github:pimili-app/dsh-maestro-progress

# Harness en ligne de commande (profil web)
dsh plugin --profile web add github:pimili-app/dsh-maestro-progress

Le profil desktop est géré par l'application Electron : le CLI refuse l'installation tant que l'application est ouverte. Pour installer avec le CLI fourni par l'application, l'activer via le menu « Gérer la commande dsh » → Installer.

Vérifier ensuite ~/.dsh/profiles/desktop/package.json : dsh.profile.bundles doit contenir "dsh-maestro-progress". Un paquet présent seulement dans dependencies ne monte aucune couche, et le journal de démarrage affiche patch: entry "maestro-progress" not found.

Développement (lien local)

dsh plugin --profile web add link:~/DSH-plugins/maestro-progress
dsh --profile web     # relancer le serveur Web

L'ajout d'un bundle (modification de package.json) demande un redémarrage du serveur ; les patches, eux, sont rechargés à chaud. Recharger ensuite l'onglet du navigateur pour reconstruire window.__DSH_BOOT__.

Configuration (cordis.patch.yml)

- insert:
    - id: maestro-progress
      name: 'dsh-maestro-progress'
      config:
        projectDir: /chemin/vers/mon-projet
        command: make maestro
        # Port Metro des tests Maestro (8083 = dev, 8084 = tests).
        metroPort: 8084

Clé	Défaut	Rôle
projectDir	workspace courant	Racine du projet Maestro (contient .maestro/).
command	make maestro	Commande du bouton Lancer les tests. Peut être une commande ciblée (maestro test .maestro/flows/login-screen.yaml --platform ios).
env	—	Variables d'environnement supplémentaires pour la commande.
maxRunMs	3600000	Durée maximale d'une exécution.
testsDir	~/.maestro/tests	Racine des journaux Maestro suivis.
scenariosFile	<projet>/.maestro/scenarios/scenarios.json	Fichier des définitions de scénarios.
platform	auto	Plateforme Maestro des scénarios (ios ou android ; par défaut iOS si un simulateur est démarré, sinon Android).
metroPort	8084	Port du serveur Metro utilisé par les tests (le dev reste sur 8083). Modifiable aussi dans le pied du panneau ; persisté dans .settings.json du plugin.
appId	host.exp.Exponent (iOS) / host.exp.exponent (Android)	Valeur APP_ID passée en --env aux scénarios.
expoUrl	construite depuis metroPort	URL Expo complète passée en --env ; court-circuite metroPort.
mailhogUrl	http://127.0.0.1:8025	Valeur MAILHOG_URL passée en --env aux scénarios.

Ce que montre le panneau

• État de l'exécution (au repos, en cours, réussi, échec, arrêté) et durée.
• Barre de progression : flows terminés / flows prévus, réussis, échoués.
• Une ligne par flow avec son état, sa durée, l'étape en cours.
• Détail d'un flow (clic) : étape en échec, message Maestro, dernières étapes avec durées, captures d'écran enregistrées par Maestro.
• Boutons Lancer les tests / Arrêter.

Scénarios E2E composés

Le panneau permet de définir des scénarios à partir des flows existants (.maestro/flows/*.yaml) : Scénarios → Nouveau scénario, nommer, puis ajouter les flows dans l'ordre voulu (flèches ↑ ↓, croix pour retirer). Chaque scénario se lance par son bouton Lancer et s'exécute comme une seule suite Maestro : runFlow: file: enchaîne les flows sélectionnés dans une seule session, sans repasser par l'interface du plugin.

Appareil cible

Chaque scénario peut cibler un appareil précis, directement sur sa ligne (liste déroulante « Automatique » + appareils détectés, enregistrée aussitôt) ou depuis l'éditeur. La liste couvre les simulateurs iOS (xcrun simctl) et les émulateurs Android connectés (adb), avec leur état. À l'exécution, l'appareil choisi est passé à Maestro (--udid <id>, alias --device) avec la plateforme correspondante ; un simulateur éteint ou un appareil absent est refusé avec un message explicite. Sans sélection, comportement automatique : iOS si un simulateur est démarré, Android sinon. L'appareil cible est affiché en badge sur la ligne du scénario.

Un scénario existant se modifie par Modifier (ou un clic sur son nom) : renommage, réordonnancement, ajout et retrait de flows, puis Enregistrer ; l'id est conservé, donc le fichier YAML généré et l'historique restent liés au même scénario. La suppression demande une confirmation sur place.

• Définitions : <projet>/.maestro/scenarios/scenarios.json (avec id, nom, flows dans l'ordre).
• Fichier généré à l'exécution : <projet>/.maestro/scenarios/<id>.yaml ; il peut être relu ou committé tel quel.
• Journaux/artefacts de chaque exécution : <projet>/.maestro/scenarios/.runs/<runId>/ (les 20 derniers sont conservés).
• Pendant l'exécution, le panneau affiche une ligne par flow du scénario (et non un seul flow global), avec l'étape courante, les durées et l'échec précis.

Étape courante en clair

Pendant l'exécution, la barre « Étape courante » et le détail des flows reformulent les commandes Maestro en phrases lisibles et localisées : « Vérifie la présence de « login-screen » », « Tape sur « login-submit » », « Exécute le flow « complete enroll to home » », « Fait défiler vers le bas jusqu'à … ». Les variables (${APP_ID || '…'}, comptes personas) sont résolues, mais un mot de passe (PERSONA_*_PASSWORD) n'est jamais affiché.

Garde-fou anti faux négatifs

Chaque scénario active par défaut une récupération, paramétrable (écran attendu, login-screen par défaut) : avant chaque flow enchaîné, le YAML généré insère un bloc conditionnel « si l'écran attendu n'est pas visible » qui relance l'application (deep link Expo), écarte l'invite « Enregistrer le mot de passe », déconnecte la session (ensure-logged-out) puis attend l'écran — deux essais. Un flow enchaîné ne démarre donc plus d'un écran périmé (login manquant, sheet restée ouverte, session du flow précédent). Le garde-fou se désactive par scénario dans l'éditeur.

Prérequis simulateur (faux négatifs système)

L'invite iOS « Utiliser un mot de passe robuste ? » recouvre l'app au premier focus d'un champ de mot de passe ; elle est invisible pour Maestro (hors hiérarchie d'accessibilité), donc l'étape suivante peut échouer alors que le flow est correct. À désactiver une fois par simulateur : Réglages → Apps → Mots de passe → Remplissage automatique et mots de passe → « Suggérer des mots de passe robustes » = off (iOS 26 ; l'équivalent existe depuis iOS 16). Le garde-fou des scénarios ne peut pas fermer cette feuille : il agit entre les flows, pas au milieu d'eux.

Modifier les flows

La section Flows du projet liste les flows (.maestro/flows/*.yaml) et les sous-flows partagés (.maestro/subflows/*.yaml). Modifier ouvre un éditeur YAML en texte brut (commentaires et mise en forme conservés) ; Enregistrer le fichier écrit directement le fichier du projet, relu au prochain lancement. Seuls les .yaml/.yml sous .maestro/ sont accessibles (1 Mo max) ; toute sortie de ce répertoire est refusée.

Où ouvrir le panneau

Il est disponible à deux endroits :

• panneau global par l'icône Maestro de la barre latérale ;
• fenêtre de droite (tools) : la même vue est enregistrée comme type d'onglet du panneau latéral droit. Dans le panneau droit (bouton d'ouverture dans l'en-tête de la conversation), ouvrir la liste d'outils (bouton +) et choisir la carte Maestro ; l'onglet peut ensuite être ancré, déplacé ou détaché comme les autres. Le bouton Ouvrir dans le panneau latéral de l'en-tête du panneau global fait la même chose en un clic.

Une suite lancée dans un terminal (make maestro) est détectée automatiquement : le panneau suit la plus récente exécution de ~/.maestro/tests.

Fonctionnement

• Moitié hôte (index.js) : lance la commande via zsh -lic dans le répertoire projet, suit ~/.maestro/tests/<horodatage>/maestro.log (flows, étapes, échecs) et sert l'API HTTP ci-dessous.
• Moitié navigateur (client.js) : enregistre l'icône sidebar.panellist, le panneau main (key: maestro) et le type d'onglet sidebar.right.pane.tab, interroge l'état toutes les 1,5 s.

API HTTP

Routes servies par la moitié hôte, JSON, préfixe /maestro-progress/api :

Méthode	Route	Rôle
GET	/state	Réglages, catalogue (flows, sous-flows, scénarios, appareils), exécution du panneau, exécution détectée dans un terminal.
POST	/action	run, stop, runScenario, saveScenario, deleteScenario, saveFlow, saveSettings.
GET	/flow?path=…	Contenu d'un flow ou sous-flow sous .maestro/.
GET	/artifact?path=…	Capture d'écran d'une exécution.

Les erreurs sont { ok: false, error: "<message>" } avec le code HTTP correspondant (400 validation, 403 origine refusée, 409 exécution déjà en cours, 500 erreur interne).

Sécurité

• Les écritures (/action) vérifient l'en-tête Origin : une requête d'une autre origine que la page du Harness est refusée (403).
• Les lectures ne renvoient aucun en-tête CORS, donc une page tierce ne peut pas lire les réponses.
• Les écritures de fichiers sont limitées aux .yaml/.yml sous .maestro/ (1 Mo max par fichier) ; toute sortie de ce répertoire est refusée.
• L'API est servie par le serveur local du Harness (loopback) et n'est pas authentifiée au-delà de ce contrôle d'origine.

Dépannage

Symptôme	Cause probable
Panneau vide ou absent	Le bundle n'est pas dans dsh.profile.bundles, ou l'application n'a pas été relancée après l'ajout.
« Maestro plugin host is unreachable »	L'API /maestro-progress/api ne répond pas : Harness ou plugin non chargé.
Lancer échoue	La commande (make maestro) échoue en dehors du panneau ; vérifier le journal de l'hôte et un lancement en terminal.
Aucun appareil dans la liste	Simulateur iOS éteint, ou adb absent pour Android.
Un flow échoue alors qu'il est correct	Invite « mot de passe robuste » d'iOS : voir Prérequis simulateur ci-dessus.

Désinstallation

dsh plugin --profile desktop remove dsh-maestro-progress   # ou --profile web

Puis redémarrer l'application. Le fichier .settings.json du paquet (port Metro) peut être supprimé sans conséquence.

Limites

• Repose sur le journal de debug de Maestro CLI (~/.maestro/tests) : la disposition et le libellé des lignes suivent Maestro 2.x ; une version qui les change fera perdre le détail des étapes (l'état des flows reste lisible).
• Pour une exécution détectée dans un terminal, le code de sortie est inconnu : le résultat est déduit des échecs de flows (resultKnown: false).
• Le panneau interroge l'API en HTTP : il fonctionne dans le GUI Web servi par dsh web (pas dans une fenêtre Electron chargée en file://).
• Au redémarrage du Harness, la dernière exécution détectée est relue depuis ~/.maestro/tests et affichée comme terminée (le code de sortie d'une exécution non lancée par le panneau reste inconnu).
• Maestro uniquement : aucun outil model-facing n'est exposé dans cette version, la vue est le seul point d'entrée.