Signaux d'automatisation et cohérence avec Playwright

Les sessions Playwright et Puppeteer peuvent montrer à une page plusieurs signaux liés à l'automatisation : l'indicateur navigator.webdriver, les liaisons du framework dans le contexte de la page, les effets de bord du Chrome DevTools Protocol (CDP) et les différences entre exécutions headless et avec fenêtre. Lorsqu'un profil est chargé, BotBrowser contrôle navigator.webdriver et, avec ENT Tier1, empêche les événements CDP protégés de la console et de l'exécution de modifier ce que la page peut observer. Votre propre code de test reste responsable des liaisons du framework, des réglages du viewport et de la cohérence entre proxy, profil et comportement du trafic. Les sections suivantes décrivent chaque catégorie de signal, expliquent pourquoi les correctifs appliqués après le chargement de la page sont plus fragiles qu'un contrôle dans le navigateur lui-même, et montrent comment vérifier le résultat dans votre propre environnement de test.

Quels signaux d'automatisation une page peut voir

Un framework d'automatisation a besoin de points d'accroche dans le navigateur pour fonctionner. Ces points se trouvent dans le même navigateur que celui qui affiche la page, de sorte que certains peuvent être lus par le JavaScript qui s'y exécute. Quatre catégories comptent en pratique, et chacune a un responsable différent lorsque vous voulez une configuration de test cohérente.

L'indicateur navigator.webdriver

La spécification W3C WebDriver définit navigator.webdriver comme un moyen pour une page de savoir que le navigateur est piloté automatiquement. Il a été conçu comme un mécanisme de transparence, de sorte qu'une session automatisée de Chromium standard renvoie normalement true. C'est l'un des signaux les plus faciles à lire, car une seule expression le renvoie. C'est aussi pourquoi c'est la première valeur à vérifier lorsqu'un environnement de test se comporte de façon inattendue.

Liaisons du framework

Playwright ajoute au contexte de la page des noms auxiliaires tels que __playwright__binding__ et __pwInitScripts pour que le framework puisse communiquer avec elle. Ces noms existent à cause de la façon dont le framework communique avec le navigateur. Ce sont des exigences de conception, pas des défauts. Puppeteer n'injecte pas les mêmes liaisons, donc son principal point de cohérence est différent : si son viewport par défaut reste actif, les dimensions de la fenêtre ne correspondent plus au profil.

Effets de bord de CDP

Playwright et Puppeteer pilotent tous deux Chromium via CDP. Certains contrôles de cohérence à l'exécution peuvent déduire une connexion CDP à partir de changements que l'automatisation peut provoquer dans le comportement de la console ou des exceptions, par exemple lorsqu'un client active les domaines Console ou Runtime. Ce signal concerne un comportement et non une propriété visible, donc un contrôle de propriétés sans anomalie ne l'écarte pas.

Une conséquence pratique découle de la protection décrite plus loin : lorsque la suppression de la console est active, votre client d'automatisation ne reçoit pas les messages de console de la page. Les équipes qui s'appuient sur un écouteur de console dans leurs propres scripts doivent l'anticiper avant la première exécution en production.

Différences entre headless et avec fenêtre

Une session headless et une session avec fenêtre peuvent différer par la géométrie de l'écran, les listes de plug-ins et le comportement graphique. Un profil fournit les mêmes valeurs prévues aux deux modes, mais le service d'affichage de l'hôte et le moteur graphique influencent encore ce qu'une page mesure. Comparez les modes que vous utilisez réellement dans votre propre environnement au lieu de supposer qu'ils coïncident. Le guide sur la cohérence des profils entre headless et avec fenêtre décrit une méthode de revue pour cela.

Pourquoi corriger après le chargement de la page est fragile

Une approche courante consiste en une extension de la communauté qui s'exécute dans la page et modifie des valeurs une fois le navigateur démarré. Elle remplace navigator.webdriver par un accesseur JavaScript, supprime des noms du framework de la portée globale et ajuste d'autres propriétés. Cette approche a des limites qui comptent pour la cohérence.

D'abord, elle travaille dans le même monde JavaScript que la page. Ce que le navigateur indiquait avant l'exécution du script est remplacé par une valeur définie depuis un script, et le remplacement peut avoir une forme différente de l'implémentation propre au navigateur. Une propriété que le navigateur n'a jamais définie et une propriété qu'un script a supprimée n'ont pas toujours le même aspect pour le code qui suit.

Ensuite, elle doit être réappliquée à chaque nouvelle page, frame et contexte, et un correctif peut ne pas atteindre tous les contextes d'exécution. Chaque couche supplémentaire est une chose de plus à garder synchronisée après une mise à jour du framework ou du navigateur. Quand la liste de correctifs s'allonge, le risque n'est pas seulement qu'un correctif échoue. La combinaison de correctifs peut produire une session qui ne se comporte plus comme aucun navigateur réel.

Enfin, un correctif qui modifie une propriété ne traite pas les autres. Changer la chaîne User-Agent, par exemple, ne touche ni navigator.webdriver, ni les liaisons du framework, ni le comportement de CDP, et peut créer un décalage entre l'identité de navigateur que vous présentez et l'environnement qui s'exécute réellement.

Certaines équipes répondent en compilant leur propre version de Chromium sans les options d'automatisation. Cela supprime une catégorie de signaux à la source, mais oblige aussi à maintenir un fork : rebaser à chaque version de Chrome, résoudre des conflits et supporter de longues compilations. Pour la plupart des équipes, cet investissement est difficile à justifier face à un navigateur maintenu qui documente ce qu'il contrôle.

Un cas limité de correctif tardif reste raisonnable. Le nettoyage addInitScript des deux noms de Playwright s'exécute avant tout script de la page et ne retire que ce que le framework a ajouté. C'est une étape petite et documentée, pas une grande couche de remplacements, et la documentation de BotBrowser la conserve dans la configuration recommandée.

Ce que BotBrowser documente pour la cohérence de l'automatisation

BotBrowser documente les contrôles suivants pour les configurations d'automatisation. Chaque ligne indique le comportement documenté et le niveau où il s'applique, afin que vous puissiez décider lesquels intégrer à votre configuration.

Contrôle	Comportement documenté	Niveau
Profil chargé (--bot-profile)	navigator.webdriver est contrôlé automatiquement ; aucune option supplémentaire n'est nécessaire	Core
--bot-disable-console-message	Empêche les événements protégés de la console et de l'exécution de modifier le comportement visible par la page tant que CDP est connecté ; actif par défaut	ENT Tier1
--bot-disable-debugger	Ignore les instructions JavaScript debugger pour que l'exécution ne s'interrompe pas	Core
--bot-always-active	Garde actifs les fenêtres et onglets qui n'ont pas le focus ; actif par défaut	PRO
--bot-port-protection	Empêche les pages distantes de détecter quels services s'exécutent sur les ports de localhost	PRO
--bot-script	Exécute votre script dans un contexte de page isolé et privilégié, sans liaisons de framework externes ni client CDP séparé	Core

L'option de console demande une lecture précise. Elle protège les chemins d'événements de la console et de l'exécution. Elle ne désactive pas le domaine CDP Runtime, de sorte que l'évaluation normale et la gestion des exceptions restent disponibles pour votre automatisation. Les sessions de diagnostic qui désactivent volontairement la protection avec --bot-disable-console-message=false modifient le comportement de CDP ; traitez-les comme une exécution de compatibilité distincte et ne comparez pas leurs résultats à ceux de la production.

--bot-script est l'option qui a la plus petite empreinte de framework, car elle ne nécessite ni Playwright ni Puppeteer. Si votre flux de travail peut s'exprimer comme un script exécuté dans le navigateur, il évite complètement les liaisons du framework. Utilisez --bot-title lorsque le titre de la page affiche le nom de l'extension.

Configurer Playwright et Puppeteer

Installez playwright-core ou puppeteer-core plutôt que les paquets complets. Les paquets complets embarquent leur propre téléchargement de Chromium, dont vous n'avez pas besoin lorsque vous lancez BotBrowser par son chemin. Gardez le profil, le chemin du binaire et le proxy dans des variables d'environnement ou dans la configuration, afin que chaque exécution enregistre les mêmes entrées.

import { chromium } from 'playwright-core';
const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    '--disable-audio-output',
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    '--proxy-server=socks5://user:pass@proxy.example.com:1080',
  ],
});
const page = await browser.newPage();
await page.addInitScript(() => {
  delete window.__playwright__binding__;
  delete window.__pwInitScripts;
});
await page.goto('https://example.com');

Créez d'abord la page, enregistrez le nettoyage, puis seulement naviguez. Le script d'initialisation doit être en place avant le premier goto, sinon la page peut s'exécuter avant que les noms soient supprimés. Ne définissez pas non plus d'options de viewport dans Playwright, car le profil doit contrôler les dimensions.

import puppeteer from 'puppeteer-core';
const browser = await puppeteer.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  defaultViewport: null,
  args: [
    '--disable-audio-output',
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    '--proxy-server=socks5://user:pass@proxy.example.com:1080',
  ],
});
const page = await browser.newPage();
await page.goto('https://example.com');

Dans Puppeteer, defaultViewport: null est la ligne importante. Sans elle, Puppeteer applique son propre viewport et remplace les dimensions d'écran fournies par le profil, et un viewport qui ne correspond pas est un problème de cohérence que vous avez créé vous-même.

Définissez le proxy avec --proxy-server (ou avec l'option de proxy par contexte), et non avec des réglages de proxy propres au framework. BotBrowser aligne le fuseau horaire, la locale et les langues sur la région du proxy seulement lorsqu'il achemine lui-même le trafic. Une valeur manuelle de --bot-timezone, --bot-locale ou --bot-languages remplace cette correspondance, tandis que les valeurs laissées sur auto continuent de suivre le proxy. Si vous chargez des profils depuis un répertoire avec --bot-profile-dir, BotBrowser en sélectionne un à chaque démarrage, et l'option de répertoire ne peut pas être combinée avec --bot-profile (le répertoire est prioritaire si les deux sont indiqués).

Sur un serveur Linux, BotBrowser a toujours besoin d'un affichage virtuel tel que Xvfb même lorsque vous le lancez avec --headless, et la variable DISPLAY doit être définie pour chaque exécution de BotBrowser. Deux options PRO sont utiles pour les tâches de longue durée. --bot-always-active est activée par défaut et garde les fenêtres et onglets à l'état actif lorsqu'ils n'ont pas le focus, ce qui correspond au comportement d'un navigateur principal. --bot-port-protection empêche les pages distantes de savoir quels services s'exécutent sur des ports locaux, comme le bureau à distance ou les serveurs de développement. Aucune de ces options ne change la façon dont Playwright ou Puppeteer se connectent, vous pouvez donc les ajouter aux arguments de lancement une fois les contrôles de base réussis.

Vérifier la configuration dans votre propre environnement de test

La vérification est un contrôle de régression de votre propre configuration. Elle indique si un lancement correspond aujourd'hui au comportement documenté et s'il y correspond encore après une mise à jour de BotBrowser, du profil ou du framework. Elle ne prédit pas la façon dont un site tiers traitera une session.

Commencez par enregistrer les entrées : version de BotBrowser, fichier de profil, arguments de lancement, version du framework, mode headless ou avec fenêtre, et région du proxy. Sans cet enregistrement, une différence ultérieure ne peut pas être rattachée à un changement.

Utilisez ensuite une page que vous maîtrisez pour lire un petit ensemble de valeurs et comparez-les à ce que le profil et vos réglages de lancement doivent produire :

1. navigator.webdriver doit valoir false une fois un profil chargé.
2. Les deux noms de liaisons de Playwright doivent être absents si le script d'initialisation s'est exécuté avant la navigation.
3. Les dimensions de la fenêtre et de l'écran doivent correspondre au profil, et les entrées de langue et de plug-ins doivent correspondre à la locale prévue.
4. Le comportement de la console doit correspondre à votre intention : avec les valeurs par défaut d'ENT Tier1, l'écouteur de console de votre client ne doit rien recevoir de la page.
5. Le fuseau horaire et les langues doivent suivre la région du proxy, ou vos valeurs explicites.

Lorsqu'une valeur diffère, la documentation indique une cause précise pour chaque cas :

Observation	Cause probable	Que changer
navigator.webdriver renvoie true	Le profil n'a pas été chargé	Vérifiez le chemin et le fichier de --bot-profile
Les noms de liaisons de Playwright sont toujours là	Le script d'initialisation s'est exécuté trop tard	Enregistrez addInitScript avant le premier goto
Les événements de console atteignent encore le client	La suppression est désactivée ou le niveau ne l'inclut pas	Vérifiez la valeur de l'option et le niveau d'abonnement
Le viewport ne correspond pas au profil	Un remplacement de viewport du framework est actif	Utilisez defaultViewport: null dans Puppeteer et évitez les options de viewport dans Playwright
Le fuseau horaire ne correspond pas à la région du proxy	Le proxy est défini seulement via les options du framework	Passez le proxy avec --proxy-server ou avec le proxy par contexte

Une page que vous contrôlez peut servir de second avis sur la même session. Lisez son résultat comme une information sur votre propre environnement, et non comme le verdict d'un tiers. Les constats qui signalent une incohérence entre profil, proxy et locale méritent d'être corrigés même si aucun site ne s'en plaint jamais.

Dans une chaîne d'intégration continue, transformez la liste en assertions qui font échouer la compilation lorsqu'une valeur attendue change. Exécutez-les dans le même mode que votre tâche de production. Si vous exploitez des tâches headless et avec fenêtre, exécutez les deux. Conservez l'enregistrement des versions à côté du résultat, afin qu'un échec après une mise à jour soit facile à rattacher au composant qui a changé.

Revue d'une exécution en échec

Supposons qu'une tâche nocturne signale que la liste de langues de votre page de test ne correspond plus à la locale du profil. Partez de l'enregistrement, pas des options. Comparez la version de BotBrowser, le fichier de profil, les arguments de lancement et la région du proxy avec la dernière exécution réussie. Dans cet exemple, seule la région du proxy a changé, parce que l'équipe a déplacé la tâche vers un autre lieu de sortie.

La documentation explique l'étape suivante. Les valeurs laissées sur auto suivent le proxy, donc la liste de langues a changé avec la région. Si l'équipe veut une locale fixe quel que soit le lieu de sortie, elle définit explicitement --bot-locale ou --bot-languages et laisse le fuseau horaire sur auto. Après ce changement, l'exécution répète les mêmes cinq contrôles et l'enregistrement est mis à jour. Le résultat est une décision documentée sur les valeurs qui suivent le proxy et celles qui sont fixées, plutôt qu'une surprise découverte plus tard.

Garder proxy, profil et trafic cohérents

Les signaux d'automatisation ne sont qu'une partie d'une session cohérente. Un profil Chrome pour Windows associé à un proxy d'un pays et à une locale d'un autre produit un décalage, sauf si vous fixez la locale ou changez la route. Décidez quels attributs doivent suivre la route et lesquels doivent rester fixes, consignez cette décision par écrit et testez-la avec la même routine que pour navigator.webdriver.

Le comportement du trafic relève de la même revue. Un script qui ouvre de nombreuses pages à un rythme qu'aucune personne n'utiliserait, ou qui répète une navigation identique selon un rythme fixe, est un schéma de comportement qu'aucun réglage du navigateur ne peut changer. BotBrowser ne remplace pas cette discipline. Gardez le volume de requêtes, le rythme et l'usage des comptes dans les règles des sites avec lesquels vous travaillez, et n'exécutez que l'automatisation que vous êtes autorisé à exécuter.

Enfin, utilisez plus d'un profil lorsque le travail demande des environnements séparés. Réutiliser un seul profil pour chaque instance revient à ce que chaque instance déclare le même environnement. --bot-profile-dir choisit un fichier dans un répertoire à chaque démarrage, ce qui donne à chaque lancement un profil différent sans code supplémentaire, et vous pouvez toujours consigner quel fichier une exécution donnée a chargé.

Limites, Selenium et questions pratiques

Dans vos propres pages de test Playwright ou Puppeteer, BotBrowser contrôle automatiquement navigator.webdriver dès qu'un profil est chargé et, avec --bot-disable-console-message (une option ENT Tier1, activée par défaut), empêche les événements CDP protégés de la console et du runtime de modifier ce que la page peut observer, ce qui vous permet de vérifier vous-même ces signaux d'automatisation avec les contrôles ci-dessus. Le comportement documenté est décrit dans cohérence de l'automatisation. Les limites sont explicites : BotBrowser ne peut pas garantir la façon dont un site tiers classe une session, ne désactive pas le domaine CDP Runtime, ne supprime pas à votre place les liaisons du framework (conservez le nettoyage addInitScript) et ne remplace pas un proxy, un profil et un comportement de trafic cohérents.

BotBrowser fonctionne-t-il avec Selenium ? Les configurations documentées utilisent Playwright et Puppeteer. Selenium communique via le protocole WebDriver, qui peut exposer des signaux supplémentaires en dehors des protections CDP décrites ici. BotBrowser contrôle toujours navigator.webdriver lorsqu'un profil est chargé, mais la protection de la console et de l'exécution se limite aux chemins CDP.

Ai-je besoin d'une extension de correctifs en plus ? La documentation n'en décrit aucune dans la configuration recommandée. Une extension qui remplace les mêmes propriétés ajoute une seconde source de valeurs, ce qui est une raison de tester d'abord sans elle. N'en ajoutez une que lorsqu'une lacune précise et vérifiée subsiste.

--bot-disable-debugger change-t-il mon débogage ? Oui. Les instructions debugger du JavaScript de la page sont ignorées, de sorte que l'exécution ne s'arrête pas dessus. Laissez l'option de côté dans une session où vous voulez cette pause, et utilisez-la pour les exécutions sans surveillance.

Et si j'ai besoin de la sortie de la console en production ? Journalisez au niveau de l'application, dans des fichiers ou un service externe, plutôt que de compter sur le transfert de la console par CDP. Pour un débogage bref, définissez --bot-disable-console-message=false dans une session séparée.

Comment garder des résultats stables entre les mises à jour ? Conservez le binaire de BotBrowser, le profil et la version du framework dans un même enregistrement de version. Refaites les contrôles ci-dessus dès que l'un d'eux change. Relisez la documentation des options que vous utilisez à chaque mise à jour, car les valeurs par défaut et les niveaux peuvent changer d'une version à l'autre.

Pour les guides de mise en route, consultez Premiers pas avec Playwright et Premiers pas avec Puppeteer. Pour l'organisation des profils, consultez Gestion des profils.

Sources publiques

• BotBrowser : pratiques de cohérence de l'automatisation
• BotBrowser : suppression de la console
• Spécification W3C WebDriver
• Chrome DevTools Protocol : domaine Runtime
• MDN : Navigator.webdriver