Agent-Browser Driver

L'orchestrateur t'a dirigé ici. Utilise ces mécaniques pour exécuter ton plan.

Contrôle les pages web et les applications de bureau Electron via la CLI agent-browser. Utilise Playwright en arrière-plan avec une instance Chromium sans interface gérée par un daemon en tâche de fond.

Quand l'utiliser

• Automatiser des flux d'application web (connexion, remplissage de formulaire, extraction de données, QA visuelle)
• Piloter des applications Electron (VS Code, Slack, Discord, Figma, Notion, Spotify)
• Vérification visuelle -- captures d'écran et superpositions d'éléments annotés
• Assertions au niveau du DOM où les snapshots de terminal sont sans objet

Si la cible est un TUI de terminal, utilise tuistory ou true-input à la place.

Prérequis

agent-browser install   # une seule fois : télécharge Chromium fourni

Pour les applications Electron, l'application cible doit être lancée avec --remote-debugging-port=<port>.

Flux de travail principal

Chaque interaction suit la même boucle :

agent-browser open <url>
agent-browser snapshot -i          # éléments interactifs uniquement -> refs comme @e1, @e2
agent-browser click @e3            # interagir en utilisant les refs
agent-browser snapshot -i          # re-snapshot (les refs s'invalident après navigation/changements DOM)
agent-browser close                # toujours fermer quand tu as fini

Chaînage de commandes

Les commandes partagent un daemon persistant, donc le chaînage avec && est sûr :

agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

Chaîne quand tu n'as pas besoin de sortie intermédiaire. Exécute séparément quand tu dois analyser les refs avant d'agir.

Référence des commandes

Navigation

Snapshot (analyse de page)

Interactions (utilise les @refs du snapshot)

Localisateurs sémantiques (quand les refs ne sont pas fiables)

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find testid "submit-btn" click

Obtenir des informations

Vérifier l'état

agent-browser is visible @e1
agent-browser is enabled @e1
agent-browser is checked @e1

Attendre

JavaScript (eval)

agent-browser eval 'document.title'

# JS complexe -- utilise --stdin pour éviter les problèmes de guillemets shell
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(Array.from(document.querySelectorAll("a")).map(a => a.href))
EVALEOF

Diff (comparer les états de page)

agent-browser diff snapshot                          # snapshot actuel vs dernier
agent-browser diff snapshot --baseline before.txt    # snapshot actuel vs fichier sauvegardé
agent-browser diff screenshot --baseline before.png  # diff pixel visuel
agent-browser diff url <url1> <url2>                 # comparer deux pages

Boîtes de dialogue

agent-browser dialog accept [text]  # accepter une alerte/confirmation/prompt
agent-browser dialog dismiss        # rejeter la boîte de dialogue

Onglets et cadres

agent-browser tab                 # lister les onglets
agent-browser tab new [url]       # nouvel onglet
agent-browser tab 2               # basculer vers l'onglet par index
agent-browser tab close           # fermer l'onglet actuel
agent-browser frame "#iframe"     # basculer vers une iframe
agent-browser frame main          # retour au cadre principal

Captures d'écran et enregistrement

agent-browser screenshot                      # enregistrer dans un répertoire temporaire
agent-browser screenshot path.png             # enregistrer dans un chemin spécifique
agent-browser screenshot --full               # capture d'écran pleine page
agent-browser screenshot --annotate           # annotée avec des libellés d'éléments numérotés
agent-browser pdf output.pdf                  # enregistrer en PDF

--annotate superpose des libellés numérotés sur les éléments interactifs. Chaque libellé [N] correspond à la ref @eN, permettant à la fois la vérification visuelle et l'interaction immédiate.

Enregistrement vidéo :

agent-browser record start ./demo.webm
# ... effectuer des actions ...
agent-browser record stop
agent-browser record restart ./take2.webm     # arrêter le courant + commencer un nouveau

L'enregistrement crée un nouveau contexte mais préserve les cookies/stockage. Explore d'abord, puis commence l'enregistrement pour des démos fluides.

Cycle de vie des refs

Les refs (@e1, @e2, ...) s'invalident chaque fois que la page change. Re-snapshot toujours après :

• Cliquer sur les liens/boutons qui naviguent
• Soumissions de formulaires
• Chargement de contenu dynamique (listes déroulantes, modales)

agent-browser click @e5           # navigue
agent-browser snapshot -i         # DOIT re-snapshot
agent-browser click @e1           # utiliser les nouvelles refs

Automation d'application Electron

Toute application Electron supporte --remote-debugging-port puisqu'elle est construite sur Chromium.

Lancer et se connecter

# macOS
open -a "Slack" --args --remote-debugging-port=9222

# Linux
slack --remote-debugging-port=9222

# Puis se connecter
sleep 3
agent-browser connect 9222
agent-browser snapshot -i

L'application doit d'abord être fermée si elle est déjà en cours d'exécution -- le drapeau ne prend effet qu'au lancement.

Gestion des onglets dans Electron

Les applications Electron ont souvent plusieurs fenêtres/webviews :

agent-browser tab                        # lister les cibles
agent-browser tab 2                      # basculer par index
agent-browser tab --url "*settings*"     # basculer par motif d'URL

Dépannage Electron

Persistance d'état

Enregistrer et restaurer les cookies/localStorage entre les sessions :

agent-browser open https://app.example.com/login
# ... flux de connexion ...
agent-browser state save auth.json

# Plus tard : charger l'état sauvegardé
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

Enregistrement/restauration automatique avec sessions nommées :

agent-browser --session-name myapp open https://app.example.com
# état auto-sauvegardé à la fermeture, auto-chargé au prochain lancement avec le même --session-name

Sessions

Le navigateur persiste via un daemon en tâche de fond. Une session est le défaut.

agent-browser --session test1 open site-a.com
agent-browser --session test2 open site-b.com
agent-browser session list
agent-browser --session test1 close
agent-browser --session test2 close

Chaque --session génère un processus Chromium séparé (~300 MB). Privilégie la navigation au sein d'une seule session. Exception : contrôler plusieurs applications Electron sur différents ports CDP.

Options globales

Débogage

agent-browser --headed open example.com   # navigateur visible
agent-browser console                     # voir les messages de console
agent-browser errors                      # voir les erreurs de page
agent-browser highlight @e1               # mettre en évidence l'élément

Pièges

• Éléments invisibles au snapshot. Les divs contenteditable et les composants personnalisés peuvent ne pas apparaître dans les snapshots d'accessibilité. Utilise eval pour interagir :

  agent-browser eval --stdin <<'EVALEOF'
  const el = document.querySelector("[contenteditable]");
  el.focus();
  el.textContent = "hello";
  el.dispatchEvent(new Event('input', { bubbles: true }));
  EVALEOF

• Noms de classe instables. Ne codifie jamais en dur les noms de classe CSS-in-JS (sc-*, css-*). Trouve les éléments par contenu textuel, style cursor: pointer, ou testid à la place.
• Délais de chargement SPA. Les applications monopage peuvent prendre 5-10s pour s'afficher après la navigation. Double-attente : wait --load networkidle puis wait 5000.
• Ordre des drapeaux. Les drapeaux globaux (--headers, --session, --cdp) doivent venir avant la sous-commande : agent-browser --headers '{}' open <url>.

Règles critiques

1. Prends toujours des captures d'écran pour la QA visuelle. Les snapshots texte manquent la mise en page, le style, l'alignement et les problèmes de z-index. Utilise screenshot --annotate quand tu as besoin à la fois d'une preuve visuelle et de refs d'éléments.
2. Une session par défaut. Navigue entre les pages avec open <url> au lieu de créer de nouvelles sessions.
3. Toujours fermer quand tu as fini. agent-browser close libère le processus Chromium.
4. Re-snapshot après chaque navigation. Les refs s'invalident.