Débuter avec l'automatisation du navigateur : carte initiale

La première exécution d'automatisation décide si le reste du projet est reproductible. Ce hub relie le groupe des premiers pas et ajoute un enregistrement borné qui nomme l'installation, le lancement, la limite de contexte et les preuves, en commençant par Playwright avec une identité adossée au profil.

BotBrowser prend en charge le lancement d'un profil autorisé depuis un pilote comme Playwright ou Puppeteer et garde les valeurs visibles du navigateur alignées sur ce profil ; il n'installe pas votre pilote, ne choisit pas votre profil et ne garantit pas qu'un site tiers acceptera la session, et il ne remplace pas la documentation du pilote.

Résumé

• Installez le navigateur et le pilote, puis prouvez que les deux démarrent avant d'écrire de l'automatisation.
• Lancez avec un profil explicite et notez quel fichier de profil l'exécution a utilisé.
• Donnez à chaque tâche son propre contexte et fermez-le dans la même exécution.
• Gardez un court enregistrement de la première exécution pour comparer la seconde.

Sommaire

• Les quatre surfaces des premiers pas
• Parcourir le groupe des premiers pas
• Lancer la première session
• Planifier le premier projet
• Rendre l'exécution répétable
• Corriger le premier échec
• Conclusion pratique

Les quatre surfaces des premiers pas

Une première exécution a quatre surfaces. L'installation couvre le paquet du navigateur, le pilote et l'alignement de version entre eux. Le lancement couvre le démarrage du processus : quel exécutable, quelle option de profil et quel mode sans interface ou avec interface. L'isolation des contextes couvre ce que possède chaque tâche : son propre contexte de navigateur, ses pages et le nettoyage qui les ferme. Les preuves couvrent ce que l'exécution laisse : la sortie console, les chaînes de version et le résultat de la vérification en propre.

Ces surfaces échouent dans un ordre qui facilite le diagnostic si vous le respectez. Un problème d'installation apparaît avant tout démarrage. Un problème de lancement apparaît comme un navigateur qui démarre sans le profil déclaré. Un problème de contexte apparaît comme un état qui fuit entre deux tâches qui devaient être indépendantes. Un problème de preuves apparaît plus tard, quand personne ne peut dire quelle compilation a produit un résultat.

Le rôle de BotBrowser dans une première exécution est étroit : il charge le profil nommé et garde les valeurs visibles du navigateur cohérentes avec lui. Tout le reste, la version du pilote, la structure du script et le nettoyage, appartient à votre code d'automatisation.

Parcourir le groupe des premiers pas

• Playwright avec une identité de profil est le chemin de lancement Playwright et ses pièges.
• Lancement et pièges de profil avec Puppeteer couvre l'équivalent Puppeteer.
• Intégration des profils avec Selenium couvre la propriété de session sous Selenium.
• Profils de navigateur : formats et rotation explique le fichier de profil que vous passerez.
• Le guide du lanceur couvre profils, proxies et configuration.
• Recettes CLI rassemble des exemples de commandes concrets.
• Automatisation légère avec le protocole DevTools couvre le chemin sans framework.
• Fixtures et isolation en automatisation couvre ce qu'une première exécution doit posséder.
• Rapports de bogues reproductibles couvre ce qu'il faut noter quand la première exécution échoue.
• Vérifier une empreinte de navigateur couvre une vérification bornée de ce que la page voit.

Le hub possède l'ordre et la forme de l'enregistrement. Chaque article lié possède le détail de sa surface et l'échec qu'elle peut produire.

Lancer la première session

Écrivez les entrées avant la première requête : le pilote et sa version, le paquet du navigateur, le fichier de profil et la vérification prévue. Lancez ensuite une session qui exerce chaque surface une fois et notez le résultat.

{
  "runId": "first-run-20261019-01",
  "declared": {
    "driver": "[email protected]",
    "browserPackage": "standard-linux-x64",
    "profile": "fresh-temporary.enc",
    "mode": "headless"
  },
  "observed": {
    "install": "executable-started",
    "launch": "profile-loaded",
    "context": "closed-after-task",
    "evidence": "console-and-check-recorded"
  },
  "firstFailure": null,
  "testedOn": "2026-10-19"
}

L'enregistrement est une donnée, pas un rapport. Il doit être assez court pour être collé dans un fil de support et assez explicite pour rejouer les quatre lignes avec le pilote et le profil notés. L'installation et le lancement sont des commandes directes qu'on colle dans un terminal.

Prouvez l'installation avant d'écrire de l'automatisation. Lancez le navigateur avec une page triviale et confirmez qu'il démarre, puis exécutez la commande de version du pilote. Un pilote qui ne démarre pas le navigateur produit une erreur qui ressemble à un problème de profil, et un navigateur qui démarre sans pilote produit une erreur qui ressemble à un problème de script. Séparer les deux vérifications prend une minute et épargne une après-midi.

Lancez avec un chemin de profil explicite. Une première exécution qui s'appuie sur un profil par défaut teste autre chose que votre automatisation. Passez le fichier de profil explicitement, puis lisez une valeur visible que le profil déclare, comme la plateforme ou le fuseau horaire, et notez-la. Si la valeur ne correspond pas, la surface en échec est le lancement, pas le script.

Donnez à chaque tâche son propre contexte. Une exécution qui réutilise un contexte entre tâches sans rapport finira par faire fuiter cookies, stockage ou permissions entre elles. Créez un contexte par tâche, exécutez la tâche et fermez le contexte dans la même fonction. Notez si la fermeture a eu lieu, car un contexte fuité reste invisible jusqu'à ce que la machine manque de mémoire.

Gardez la première vérification en propre et petite. Utilisez une page contrôlée par votre équipe, à version figée, et affirmez une seule chose : le profil s'est chargé, la page s'est affichée ou l'interaction s'est terminée. Une première exécution contre un site tiers mesure aussi la politique de ce site, et son échec ne dit pas laquelle de vos quatre surfaces est en cause.

Notez les versions des deux côtés. La version du pilote et celle du paquet du navigateur vont dans le même enregistrement que le résultat, car une configuration partagée échoue à une couche différente d'une mise à jour du pilote. Quand la fois suivante se comporte autrement, les deux enregistrements montrent quel côté a bougé.

Choisissez le mode sans interface délibérément. Une première exécution sans interface est plus facile à automatiser et à porter en CI, et une exécution avec interface est plus facile à déboguer quand la page s'affiche autrement. Notez le mode utilisé, car changer de mode entre deux exécutions est une autre expérience, et un écart de rendu sans interface n'est pas une preuve du comportement avec interface.

Nettoyez même quand l'exécution échoue. Enveloppez la session pour que le contexte et le navigateur se ferment en cas d'exception comme en cas de succès. Une première exécution qui laisse un processus de navigateur vivant fait mesurer l'état résiduel à la seconde, et c'est ainsi qu'une configuration simple devient un échec intermittent.

Planifier le premier projet

Ce qu'il faut décider juste après la première exécution, c'est la forme du projet. Gardez trois choses séparées dès le départ : le code de lancement qui connaît le navigateur et le profil, le code de tâche qui connaît la page testée, et le code de fixture partagé par les deux. Quand tout est mélangé, chaque nouvelle tâche recopie les détails de lancement et un changement de profil doit être appliqué à une douzaine d'endroits.

Mettez le chemin du profil dans une valeur de configuration plutôt qu'en littéral dans un script. La première exécution utilise en général un profil et la seconde en a besoin d'un autre, que ce soit pour tester la rotation ou pour isoler une équipe ; l'article sur les formats de profil explique quel fichier passer. Une valeur de configuration en fait une modification d'une ligne et fait du profil une entrée enregistrée plutôt qu'une constante invisible.

Faites du lancement une fonction comme createSession({ profile, headless }) qui retourne un objet session. L'objet session possède le navigateur, le contexte et une méthode de fermeture. La tâche reçoit la session et ne voit jamais les options de lancement. Cela reflète la façon dont Playwright et Puppeteer décrivent la propriété du contexte, et une tâche écrite pour un pilote peut être adaptée à un autre sans réécrire la logique de page.

Versionnez la page de fixture avec le code. Un fixture qui change sans changement de version rend deux exécutions incomparables, et le premier symptôme est un écart qui ressemble à une régression du navigateur. Une chaîne de version dans le fixture et dans l'enregistrement suffit à les distinguer.

Choisir le pilote pour le travail, pas pour la démo

Playwright, Puppeteer, Selenium et un client direct du protocole DevTools pilotent le même navigateur, et chacun impose un compromis différent. Playwright offre une API de contextes mature et un lecteur de traces, Puppeteer a une surface plus petite et une longue histoire dans l'automatisation Chrome, Selenium correspond à un standard inter-navigateurs plus large, et un client de protocole supprime le framework au prix de la plomberie.

Pour une première exécution, choisissez le pilote que votre équipe utilise déjà ailleurs. Le chemin de lancement est la partie testée, et un pilote inconnu ajoute un second inconnu. Le groupe lié ci-dessus couvre le lancement avec profil pour chaque pilote principal et le chemin protocole pour un montage sans framework.

Quel que soit le pilote, gardez l'option de profil dans les options de lancement et non dans un script au niveau de la page. Un contournement au niveau de la page qui fixe une valeur après chargement teste quelque chose que le navigateur n'a pas fourni, et il divergera du profil déclaré à la navigation suivante.

Décider ce que la première exécution doit prouver

Une première exécution est une vérification à une seule question, et la question doit être écrite avant le script. « Le navigateur démarre-t-il avec ce profil ? » est une bonne première question. « La page s'affiche-t-elle sur la plateforme déclarée ? » est une bonne seconde. « Le site accepte-t-il la session ? » est une question sur le site, et elle arrive plus tard, dans un test que vous possédez.

Écrivez le résultat attendu comme une valeur, pas comme une impression. Par exemple, attendez que navigator.platform rapporte la valeur déclarée dans le profil, ou que le fixture en propre retourne un objet d'état de forme fixe. Une valeur se compare entre exécutions ; une impression non.

Notez le résultat réel à côté du résultat attendu. Une première exécution qui se contente de passer est moins utile qu'une exécution qui note ce qu'elle a observé, car la comparaison suivante a besoin des deux côtés. Quand la valeur observée change après une mise à jour du pilote, l'enregistrement montre exactement quel champ a bougé.

Rendre l'exécution répétable

L'intérêt d'une première exécution est qu'elle transforme la seconde en comparaison plutôt qu'en enquête. Cela n'arrive que si la seconde répète les mêmes entrées déclarées et produit le même enregistrement. Gardez l'identifiant d'exécution, la version du pilote, le paquet et le profil dans l'enregistrement, et rejouez la même vérification avant d'en changer un seul.

Mettez toute la séquence derrière une commande, par exemple npm run first-run, qui sort en erreur si elle échoue. Une configuration documentée en cinq étapes manuelles devient une configuration que personne n'exécute. Une commande qui n'installe rien, lance le navigateur avec le profil configuré, exécute la vérification en propre et écrit l'enregistrement est une configuration qui tourne en intégration continue et dans le checkout d'un nouveau collègue le même jour.

Traitez la première exécution réussie comme un test de régression et non comme un jalon. La vérification qui a prouvé que la configuration fonctionne doit continuer de tourner pour qu'une mise à jour ultérieure du pilote ou du paquet soit attrapée par le même test. Une première exécution qui n'existe que dans une capture de discussion ne protège rien.

Garder le profil et le nettoyage ensemble

Le fichier de profil et le chemin de nettoyage sont les deux extrémités de la même décision. Un profil jamais supprimé s'accumule sur la machine, et un contexte jamais fermé garde son état vivant. Les deux problèmes apparaissent comme une pression mémoire plutôt que comme une erreur évidente, et les deux s'évitent facilement quand la première exécution note d'où venait le profil et quels contextes ont été fermés.

Préférez un profil temporaire neuf (profileClass: "fresh-temporary") pour la première exécution, et notez la classe plutôt que le chemin si le profil contient des éléments sensibles. Un profil neuf garde la première exécution indépendante de l'activité antérieure et rend la comparaison avec la seconde significative. Un profil de longue durée est une étape ultérieure légitime, et elle doit être délibérée.

Quand l'exécution utilise un profil d'un magasin partagé, notez le magasin et la règle de sélection plutôt que le nom de fichier complet, afin qu'un relecteur voie comment le profil a été choisi sans recevoir le profil.

Automatiser les vérifications déjà faites à la main

Une fois la première exécution notée, la plupart de ses lignes peuvent être automatisées. La vérification d'installation devient une assertion de version. Celle de lancement, une lecture d'une valeur déclarée. Celle de contexte, une assertion de fermeture. Celle de preuves, le fichier d'enregistrement lui-même. Les automatiser ne change pas ce qu'elles prouvent ; cela les rend assez peu coûteuses pour tourner à chaque changement.

Gardez l'automatisation honnête sur ses limites. Que le navigateur ait démarré ne prouve pas qu'une page se comporte correctement, et que la page se soit affichée ne prouve pas qu'un service a accepté la session. Chaque ligne automatisée doit affirmer une chose et rapporter un résultat, pour qu'un échec pointe une surface et non toute la configuration.

Lancez la première exécution automatisée (npm run first-run) avant de fusionner un changement du code de lancement. Ce code est petit et central, et un changement y affecte toutes les tâches, donc le test de régression le moins cher est celui qui existe déjà.

Documenter l'unique commande que l'équipe tapera vraiment

Une documentation qui énumère chaque option dont un nouvel utilisateur pourrait avoir besoin est moins utile qu'une commande qui marche. Mettez la commande en haut, l'explication en dessous, et assurez-vous que la commande du document est celle que lance l'automatisation. Une commande documentée qui a divergé du code est pire qu'aucune commande, parce qu'elle enseigne un montage que personne n'utilise.

Incluez la sortie attendue dans la documentation, pas seulement la commande. Quelqu'un qui arrive pour la première fois doit savoir à quoi ressemble le succès, et un fichier d'enregistrement avec les quatre lignes remplies est une cible plus claire qu'une phrase disant que ça a marché.

Revoyez la commande quand le pilote ou le paquet change. La première exécution est la partie du projet la plus vite obsolète, parce que c'est celle que chacun configure une fois puis ne regarde plus.

Corriger le premier échec

Si rien ne démarre, vérifiez d'abord la surface d'installation : l'exécutable, ses permissions et la capacité du pilote à l'atteindre. Si le navigateur démarre mais la valeur du profil ne correspond pas, vérifiez le lancement : le nom de l'option, le chemin et le format du profil. Si deux tâches partagent de l'état, vérifiez la surface de contexte : où le contexte a été créé et où il a été fermé. Si le résultat n'est pas reproductible, vérifiez les preuves : quelles versions et quelles entrées ont été notées.

Corrigez une surface par exécution et conservez l'enregistrement. Une première exécution qui se termine sur une surface nommée est prête à devenir le modèle du reste du projet.

Conclusion pratique

Une première exécution répétable, ce sont quatre enregistrements : installation, lancement, contexte et preuves. Utilisez ce hub pour les ordonner et le groupe pour le détail, et limitez chaque conclusion au pilote, au paquet et au profil qui l'ont produite.

Sources publiques

• Playwright : contextes de navigateur
• Puppeteer : gestion du navigateur
• MDN : WebDriver
• Documentation BotBrowser : premiers pas
• Documentation BotBrowser : gestion des profils