Puppeteer + BotBrowser : pièges de lancement et de profil

Si vous voulez la configuration la plus courte de BotBrowser avec Puppeteer, commencez par la page de documentation consacrée à Puppeteer. Après un premier lancement réussi, trois erreurs d'intégration brisent souvent discrètement la cohérence du profil ; leurs symptômes permettent de les reconnaître et de les corriger sans toucher au code de vos pages.

Puppeteer est une couche de contrôle. Il décide quel binaire démarre, quelles options de lancement s'appliquent et quelles commandes passent par la connexion DevTools. BotBrowser est le navigateur qui charge un profil et le présente aux pages. Lorsque les deux sont correctement reliés, vos sélecteurs, votre logique de navigation et votre extraction de données fonctionnent exactement comme avant. Lorsqu'ils sont mal reliés, le profil peut se charger alors que quelque chose autour de lui le contredit, et cette contradiction est plus difficile à diagnostiquer qu'un plantage franc.

Résumé

• Démarrez puppeteer-core avec un executablePath explicite ; le Chromium fourni par le paquet puppeteer ne charge jamais de profil.
• Gardez defaultViewport: null ; une page neuve qui mesure 800x600 signale que l'écrasement de viewport de Puppeteer est toujours actif.
• Envoyez les commandes BotBrowser telles que BotBrowser.setCustomHeaders par browser.target().createCDPSession(), pas par une session de page.
• Placez --bot-profile, --proxy-server, --bot-timezone, --bot-locale et --bot-languages dans args, puis comparez navigator.languages et screen.width avec le profil.

Sommaire

• Trois erreurs de lancement qui brisent la cohérence du profil
• Lancer BotBrowser avec puppeteer-core
• Envoyer les commandes CDP de BotBrowser sur une session de niveau navigateur
• Ajouter les réglages de proxy, de fuseau horaire et de langue
• Vérifier le lancement et résoudre les pannes courantes
• Ce que BotBrowser couvre et ce qu'il ne couvre pas
• À retenir

Trois erreurs de lancement qui brisent la cohérence du profil

La plupart des intégrations Puppeteer qui échouent remontent à l'une de trois causes. Chacune a un symptôme différent, il est donc utile de les reconnaître d'après ce que vous observez plutôt que d'après ce que vous avez configuré.

• Le mauvais binaire démarre. Le paquet puppeteer classique télécharge sa propre version de Chromium, et un lancement sans executablePath explicite utilise cette version. Le navigateur s'ouvre et les pages se chargent, mais aucun profil BotBrowser n'intervient.
• Puppeteer écrase le viewport. Puppeteer applique un viewport par défaut de 800x600 à chaque nouvelle page, sauf si vous désactivez ce comportement. Un profil qui décrit un écran plus grand se retrouve à côté d'une page qui signale une petite fenêtre, et les deux valeurs se contredisent.
• Une commande BotBrowser part vers la mauvaise session. BotBrowser ajoute ses propres commandes CDP, accessibles sur la session de niveau navigateur. Une session de niveau page ne les connaît pas, et l'appel échoue avec une erreur de méthode introuvable.

Aucun de ces cas ne provoque de plantage évident. Le premier vous donne un Chromium parfaitement normal, le deuxième une page normale avec une taille de fenêtre étrange, et le troisième un appel en échec que l'on met facilement sur le compte d'une faute de frappe. C'est pourquoi ils passent si souvent la revue de code.

La cohérence du profil signifie simplement que les valeurs qui vont ensemble s'accordent entre elles. Une session qui signale un écran, une taille de fenêtre, une liste de langues et un fuseau horaire doit signaler des combinaisons compatibles. Le profil fournit ces valeurs : tout ce qui, en dehors du profil, modifie l'une d'elles, comme une option Puppeteer ou un script oublié, crée un désaccord que le profil n'avait pas prévu.

Un bon lancement a une signature courte. Le processus démarré est le binaire BotBrowser, le chemin du profil est transmis comme argument de lancement, le viewport par défaut est désactivé et toute commande propre à BotBrowser passe par une session créée depuis la cible du navigateur. Les sections suivantes parcourent ces quatre points, puis montrent comment les confirmer de l'extérieur.

Gardez à l'esprit ce que cette liste est et n'est pas. Elle couvre la configuration de lancement : quel binaire, quels arguments, quel comportement de viewport, quelle session. Elle ne change pas la façon dont Puppeteer pilote les pages et n'affirme rien sur la manière dont un site précis traitera la session obtenue.

Lancer BotBrowser avec puppeteer-core

Installer les composants

La documentation de BotBrowser énumère quatre prérequis pour Puppeteer : un binaire BotBrowser installé, Node.js 18 ou une version plus récente, le paquet puppeteer-core et un fichier de profil. Les environnements de production utilisent un profil .enc chiffré, et ce profil doit correspondre à la version de BotBrowser que vous exécutez.

• Un binaire BotBrowser, téléchargé depuis le dépôt BotBrowser et installé comme l'indique le guide d'installation.
• Node.js 18 au minimum.
• Le paquet npm puppeteer-core.
• Un fichier de profil, normalement avec l'extension .enc.

Le choix du paquet compte plus qu'il n'y paraît. Le paquet complet puppeteer embarque le téléchargement d'un navigateur, précisément ce que vous ne voulez pas lancer par accident. puppeteer-core fournit la même API d'automatisation sans navigateur fourni, ce qui vous oblige à indiquer quel exécutable démarrer. Cette exigence est le point d'intégration : vous transmettez le chemin du binaire BotBrowser, et Puppeteer le démarre.

npm init -y
npm install puppeteer-core

Un lancement minimal

Le lancement minimal documenté définit quatre éléments qu'un script Puppeteer standard omet ou laisse à leur valeur par défaut.

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  browser: 'chrome',
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  defaultViewport: null,
  args: [`--bot-profile=${process.env.BOT_PROFILE_PATH}`],
});

const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

Chaque option a un rôle.

• browser: "chrome" sélectionne le démarrage en mode Chrome, ce que demande la documentation de BotBrowser avec puppeteer-core. Si un lancement échoue dans puppeteer-core, cette option et le chemin de l'exécutable sont les deux premières choses à vérifier.
• executablePath pointe vers le binaire BotBrowser. Le lire depuis une variable d'environnement garde les chemins propres à chaque machine hors du script et permet au même code de fonctionner sur un portable comme sur un serveur.
• headless: true s'exécute sans fenêtre visible. Désactivez-le pendant le débogage si vous voulez observer la session.
• defaultViewport: null désactive l'écrasement du viewport par Puppeteer, expliqué dans la section suivante.
• args transporte les options de BotBrowser. --bot-profile charge le profil, et un chemin absolu évite les surprises lorsque le répertoire de travail diffère d'une machine à l'autre.

Le code de page qui suit l'appel de lancement est du Puppeteer ordinaire. Rien dans newPage, goto, les sélecteurs ou close n'est propre à BotBrowser, et c'est précisément le but : migrer un projet existant ne devrait toucher que le bloc de lancement.

Pourquoi defaultViewport doit valoir null

La référence des options de lancement de Puppeteer décrit defaultViewport comme le réglage qui donne à chaque page un viewport cohérent, avec une valeur par défaut de 800x600. Le mettre à null désactive cette valeur. Dans une suite de tests classique, c'est une commodité. Avec un profil BotBrowser, cela devient un conflit, car le profil décrit déjà les dimensions d'écran et de fenêtre que la session doit signaler.

Quand l'écrasement reste actif, Puppeteer dimensionne chaque page à 800x600 après que le navigateur a chargé le profil. Le profil dit une chose et la page en mesure une autre. Quiconque compare les dimensions de l'écran et les dimensions intérieures de la fenêtre verra une combinaison qu'aucun appareil réel ne produit. C'est la raison la plus fréquente pour laquelle un premier test paraît incorrect alors que le profil s'est chargé sans erreur.

La correction tient en une ligne et le symptôme se confirme facilement : si l'intérieur de la fenêtre d'une nouvelle page mesure 800x600, le viewport par défaut est encore actif. Définissez defaultViewport: null, relancez, et la page reprendra ses dimensions du profil. Gardez cette ligne dans chaque appel de lancement que vous écrivez, y compris dans les scripts copiés depuis d'anciens exemples Puppeteer, car la plupart reposent sur la valeur par défaut.

Migrer un projet existant

Un projet Puppeteer existant demande trois modifications, toutes dans le bloc de lancement. Remplacez la dépendance puppeteer par puppeteer-core, afin qu'aucun navigateur fourni ne soit téléchargé et que chaque lancement doive nommer son exécutable. Remplacez les options de lancement par le lancement minimal présenté plus haut, en renseignant le chemin du binaire BotBrowser et celui du profil. Supprimez ensuite toute valeur de defaultViewport et restez prudent avec les appels explicites de viewport, car dimensionner une page à la main écrase ces mêmes dimensions du profil.

Tout ce qui suit le bloc de lancement reste tel quel : navigation, attentes, sélecteurs, extraction de données, captures d'écran et nettoyage. Si un projet comporte plusieurs points de lancement, par exemple un dans un utilitaire de test et un dans un outil autonome, mettez-les tous à jour. Un seul lancement oublié avec l'ancienne configuration suffit à ramener le navigateur fourni ou l'écrasement du viewport.

Fermez ce que vous lancez. Chaque appel à puppeteer.launch démarre un processus de navigateur distinct ; entourez donc le travail d'un try et d'un finally, et appelez browser.close() dans le bloc finally, sinon une exécution en échec laisse un processus derrière elle.

Gardez les valeurs propres à une machine hors du code source. Le chemin du binaire, le chemin du profil et les identifiants du proxy fonctionnent bien comme variables d'environnement, comme dans les exemples ci-dessus, car le même script s'exécute alors sans modification sur un portable, un runner d'intégration continue et un serveur, et les identifiants restent hors du contrôle de version.

Envoyer les commandes CDP de BotBrowser sur une session de niveau navigateur

Puppeteer expose le Chrome DevTools Protocol via des objets CDPSession. Les commandes standard du protocole fonctionnent dans n'importe quelle session. Les commandes propres à BotBrowser, comme BotBrowser.setCustomHeaders, appartiennent au navigateur dans son ensemble ; elles sont donc disponibles sur une session rattachée à la cible du navigateur.

const cdp = await browser.target().createCDPSession();

await cdp.send('BotBrowser.setCustomHeaders', {
  headers: { 'x-client-app': 'bb' },
});

L'appel à observer est browser.target().createCDPSession(). Il crée une session sur le navigateur lui-même. Le plus familier page.createCDPSession() crée une session sur une seule cible de page, et cette session ne reconnaît pas les commandes BotBrowser. Le résultat est une erreur de méthode introuvable qui ressemble à une faute de frappe dans le nom de la commande, même quand le nom est exact.

Quand vous voyez cette erreur, vérifiez d'où vient la session avant de vérifier l'orthographe. Si la session vient d'une page, créez-en une nouvelle depuis la cible du navigateur et renvoyez la commande. Une seule session de niveau navigateur suffit pour tout le script : vous pouvez la créer une fois après le lancement et la réutiliser pour chaque commande BotBrowser.

Nommer clairement rend la portée visible en revue de code. Une variable appelée browserCdp, créée depuis browser.target(), se confond difficilement avec une session de page, alors qu'une variable générique appelée client, créée dans un utilitaire de page, est facile à mal utiliser des mois plus tard par quelqu'un qui ne l'a pas écrite.

Les fonctions standard de Puppeteer gardent leur chemin habituel. Seules les commandes propres à BotBrowser ont besoin de la session de niveau navigateur, et le reste du script continue d'utiliser les méthodes de page habituelles.

Ajouter les réglages de proxy, de fuseau horaire et de langue

Un profil décrit un appareil. Les réglages réseau et régionaux décrivent l'endroit où cet appareil semble se trouver. La documentation de BotBrowser transmet les deux types de réglages via args, à côté de --bot-profile.

const browser = await puppeteer.launch({
  browser: 'chrome',
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  defaultViewport: null,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    '--proxy-server=socks5://user:[email protected]:1080',
    '--bot-timezone=Asia/Tokyo',
    '--bot-locale=ja-JP',
    '--bot-languages=ja-JP,ja,en-US,en',
  ],
});

Transmettez le proxy avec --proxy-server dans args. BotBrowser accepte les identifiants dans l'URL du proxy, et la documentation déconseille les schémas d'authentification de proxy propres au framework, car les valeurs géographiques déduites de l'adresse de sortie ne seront pas alignées si le proxy est configuré hors du navigateur. Si le fuseau horaire ne correspond pas à la région du proxy, examinez d'abord comment le proxy a été configuré avant de regarder ailleurs ; Configuration du proxy détaille les formes d'identifiants et de syntaxe.

Lorsqu'un proxy est défini, le comportement par défaut documenté est que BotBrowser déduit le fuseau horaire, les paramètres régionaux et les langues de l'adresse de sortie du proxy. Les options explicites --bot-timezone, --bot-locale et --bot-languages remplacent ces valeurs déduites pour les réglages qu'elles définissent. Utilisez-les pour une région fixe, et omettez-les si vous voulez que les valeurs suivent le proxy. Plusieurs de ces options relèvent de niveaux supérieurs de BotBrowser ; consultez donc la référence des options de la CLI pour savoir quel niveau s'applique à votre configuration avant de vous y fier.

Si vous exécutez plusieurs navigateurs depuis une même machine, donnez à chacun son propre --user-data-dir. La documentation présente les conflits entre instances comme un problème connu et le répertoire unique comme la solution, car il garde le stockage et l'état de session séparés.

Le proxy par contexte via browser.createBrowserContext() mérite une lecture attentive de vos versions. L'acceptation d'une option de proxy à cet endroit dépend de la version de Puppeteer et du niveau de BotBrowser ; considérez-le comme quelque chose à tester sur votre propre configuration, et non comme une fonction prise en charge par toutes les combinaisons.

Vérifier le lancement et résoudre les pannes courantes

La vérification doit se faire côté page, car c'est ce que voit un site web. Ouvrez une page, lisez quelques valeurs et comparez-les au profil que vous avez chargé.

const page = await browser.newPage();
await page.goto('https://example.com');

const reported = await page.evaluate(() => ({
  userAgent: navigator.userAgent,
  languages: navigator.languages,
  screenWidth: screen.width,
  screenHeight: screen.height,
  innerWidth: window.innerWidth,
  innerHeight: window.innerHeight,
  pixelRatio: window.devicePixelRatio,
}));

console.log(reported);

Lisez la sortie en trois étapes. Le user agent et la liste de langues doivent correspondre à ce que décrivent le profil et vos options régionales. Les dimensions de l'écran doivent correspondre à l'écran du profil. Les dimensions intérieures de la fenêtre doivent être cohérentes avec cet écran et ne pas valoir exactement 800x600. Si elles valent 800x600, retournez au bloc de lancement et cherchez l'écrasement du viewport.

Cet extrait est un contrôle de bon sens pour votre propre intégration, pas une suite de tests ni une promesse concernant un site. Comparez la sortie au profil que vous avez chargé, pas à votre propre machine. L'intérêt du contrôle est que les valeurs proviennent du profil ; une correspondance parfaite avec l'hôte serait donc une raison de regarder à nouveau. Exécutez-le une fois après toute modification du bloc de lancement, et de nouveau lorsque vous déplacez le script vers une autre machine, car un chemin de binaire différent ou un exemple copié est le point d'entrée de la plupart des régressions.

Quand quelque chose cloche, le symptôme désigne en général directement la cause.

Symptôme	Cause probable et correction
Le viewport mesure 800x600	Le viewport par défaut est actif. Définissez defaultViewport: null.
Le lancement échoue dans puppeteer-core	Ajoutez browser: "chrome" et vérifiez que executablePath pointe vers le binaire BotBrowser.
Le profil ne semble pas s'appliquer	Le mauvais binaire a peut-être démarré. Vérifiez le chemin de l'exécutable et utilisez un chemin absolu pour le profil.
Les commandes BotBrowser renvoient méthode introuvable	La session vient d'une page. Créez-la avec browser.target().createCDPSession().
Le fuseau horaire ou les langues ne correspondent pas au proxy	Transmettez le proxy avec --proxy-server dans args, pas avec une option propre au framework.
Plusieurs instances se gênent mutuellement	Donnez à chaque instance un --user-data-dir unique.

Si le profil ne semble pas s'appliquer du tout, procédez de l'extérieur vers l'intérieur ; les combinaisons d'options utilisées dans ces exemples sont rassemblées dans les recettes CLI. Vérifiez que le processus démarré est le binaire BotBrowser et non un Chromium standard, vérifiez que le chemin du profil est absolu et que le fichier existe, et vérifiez que le paquet de profil correspond à la version majeure de BotBrowser installée, car la documentation demande des versions concordantes. Ne changez qu'une chose à la fois, puis relancez, afin de savoir quelle modification a joué.

Une dernière question fréquente : les plugins qui corrigent la page depuis JavaScript sont-ils encore nécessaires ? Ils ne font pas partie de la configuration documentée de BotBrowser. Le profil est appliqué par le binaire du navigateur que vous lancez, et la liste de lancement ci-dessus ne dépend pas de correctifs au niveau de la page. Les ajouter vous donne une couche de plus à analyser quand un lancement semble faux ; testez donc d'abord la configuration documentée et n'ajoutez autre chose que pour une raison que vous savez formuler.

Prouver que les valeurs viennent du profil, pas de la machine

Comparer les valeurs remontées avec sa propre machine répond à la mauvaise question. Une session qui a démarré discrètement un Chromium ordinaire remonte les valeurs de la machine, et un lancement correct peut aussi s'en approcher lorsque le profil a été généré pour un appareil similaire. Aucun des deux résultats ne dit si le profil a été appliqué.

La vérification qui y répond utilise deux profils. Exécutez le même script deux fois, chargez un profil différent à chaque exécution et imprimez les mêmes champs. Gardez tout le reste identique : même chemin d'exécutable, même réglage de fenêtre d'affichage, même page.

// launch-report.mjs: une exécution par profil, conservez chaque sortie
const fields = await page.evaluate(() => ({
  ua: navigator.userAgent,
  langs: navigator.languages.join('|'),
  screen: `${screen.width}x${screen.height}`,
  inner: `${window.innerWidth}x${window.innerHeight}`,
  dpr: window.devicePixelRatio,
}));
console.log(JSON.stringify(fields));

BOT_PROFILE_PATH=/path/profile-a.enc node launch-report.mjs > a.json
BOT_PROFILE_PATH=/path/profile-b.enc node launch-report.mjs > b.json
diff a.json b.json

Trois résultats, trois problèmes différents.

Résultat	Signification	Étape suivante
diff affiche les champs qui divergent	Les deux profils sont chargés et les valeurs suivent le profil	Rien à corriger au lancement
diff n'affiche rien	Aucun profil n'a atteint le navigateur	Vérifiez executablePath et que le processus démarré est bien le binaire BotBrowser
Seul ua diffère, screen et inner sont identiques	Le réglage de fenêtre d'affichage est toujours actif, ou les deux profils décrivent le même écran	Contrôlez defaultViewport: null, puis comparez les champs d'écran du profil
ua identique mais un champ propre au profil manque	Le fichier de profil n'a pas été chargé ou ne correspond pas à la version majeure du binaire	Comparez le paquet de profil avec la version majeure installée de BotBrowser

La comparaison de deux profils coûte peu : elle ne demande ni site cible ni réseau au-delà d'une page vide. Lancez-la au premier branchement de Puppeteer, puis de nouveau chaque fois que le script pointe vers un nouveau binaire ou vers un exemple copié, car ce sont les deux endroits où la configuration de lancement change sans que personne ne le remarque.

Si la comparaison n'affiche rien du tout, cessez de déboguer la page. Aucun newPage, goto ni sélecteur ne fait appliquer un profil ; la décision a déjà été prise dans l'appel de lancement.

Ce que BotBrowser couvre et ce qu'il ne couvre pas

BotBrowser documente le lancement de Puppeteer via puppeteer-core avec browser réglé sur chrome, un executablePath, --bot-profile et defaultViewport: null, de sorte que les dimensions de viewport du profil restent prioritaires sur la valeur par défaut de 800x600 de Puppeteer, et que les commandes CDP de BotBrowser sont envoyées sur une session de niveau navigateur. Pour vous, cela donne une recette de lancement courte et vérifiable : si une session semble incohérente, vous pouvez la comparer à ces quatre points et trouver celui qui diffère. BotBrowser ne peut pas corriger un lancement que Puppeteer écrase, comme un defaultViewport laissé à sa valeur par défaut, il ne remplace pas une configuration de lancement Puppeteer correcte et il ne garantit pas la manière dont un site cible traite la session.

Les mêmes limites s'appliquent aux sujets voisins. Les options de proxy et de région dépendent du proxy et de votre niveau de BotBrowser, et la prise en charge du proxy par contexte dépend à la fois de la version de Puppeteer et du niveau. Comparer BotBrowser aux plugins qui corrigent la page ne dit que le niveau auquel chaque approche agit, puisque l'une passe par le binaire du navigateur et l'autre par du JavaScript injecté. Cela ne dit rien de la réaction d'un site à l'une ou à l'autre.

Pour des configurations voisines, lisez Premiers pas avec Playwright si vous utilisez aussi Playwright, Recettes CLI pour les combinaisons d'options, Configuration d'un serveur headless pour l'exécution sur un serveur et Configuration du proxy pour la syntaxe du proxy et les identifiants.

Sources publiques

• Dépôt BotBrowser
• Documentation BotBrowser : premiers pas avec Puppeteer
• API Puppeteer : LaunchOptions

À retenir

Quatre décisions de lancement se vérifient avant toute ligne de code de page : executablePath désigne le binaire BotBrowser, --bot-profile pointe vers un fichier .enc absolu qui correspond à la version majeure installée, defaultViewport: null écarte l'écrasement 800x600 de Puppeteer, et les commandes BotBrowser passent par la session issue de browser.target(). Face à une session incohérente, reprenez ces quatre points avant de modifier les sélecteurs ou la navigation. BotBrowser configure le lancement ; il ne corrige pas une option que Puppeteer écrase et ne décide pas du traitement réservé à la session par un site cible.