Automatisation de navigateur avec Playwright et profils d'empreinte

Introduction

Playwright est le framework d'automatisation de navigateur open-source de Microsoft, connu pour son auto-attente fiable, son support multi-navigateurs et son API puissante pour controler le comportement du navigateur. BotBrowser remplace le binaire Chromium standard par un binaire qui produit une empreinte coherente controlee par des fichiers de profil. Ensemble, Playwright gere la logique d'automatisation tandis que BotBrowser gere la couche d'identite du navigateur.

Ce guide couvre tout ce dont vous avez besoin pour demarrer : installation, configuration de lancement de base, configuration du proxy, contextes de navigateur multiples, gestion du viewport, pieges courants et patterns de deploiement en production. A la fin, vous disposerez d'une configuration fonctionnelle combinant les capacites d'automatisation de Playwright avec le controle d'empreinte de BotBrowser.

Impact sur la confidentialite : pourquoi Playwright + BotBrowser

Le Playwright standard utilise un binaire Chromium de base qui expose la veritable empreinte du systeme. Chaque instance de navigateur revele les memes caracteristiques de la machine hote : le meme GPU, les memes polices, la meme resolution d'ecran, et des signaux specifiques a l'automatisation qui indiquent que le navigateur est controle par programme.

BotBrowser change cette equation. Chaque instance de navigateur peut charger un profil d'empreinte different, presentant une identite de navigateur unique qui est coherente a travers tous les signaux. Le framework d'automatisation gere la navigation, l'extraction de donnees et la logique d'interaction. La couche d'identite du navigateur fait ressembler chaque instance a une session de navigateur distincte et legitime.

Cette separation des responsabilites est propre et pratique. Vous n'avez pas besoin de modifier votre code d'automatisation Playwright pour fonctionner avec BotBrowser. L'integration se fait au niveau de la configuration de lancement, et tout le reste (interactions de page, selecteurs, assertions, interception reseau) fonctionne exactement comme avec Playwright standard.

Contexte technique

Pourquoi playwright-core et non playwright

Le package npm standard playwright inclut son propre binaire Chromium. Lorsque vous installez playwright, il telecharge et gere automatiquement les binaires de navigateur. C'est pratique pour un usage general mais incompatible avec BotBrowser, qui fournit son propre binaire Chromium modifie.

Le package playwright-core fournit la meme API sans navigateurs inclus. Il vous oblige a specifier un executablePath au lancement, ce qui est exactement ce dont vous avez besoin pour pointer Playwright vers le binaire BotBrowser.

# Installer playwright-core, pas playwright
npm install playwright-core

Comment fonctionne la configuration de lancement

Lorsque vous appelez chromium.launch(), Playwright lance un processus Chrome avec les arguments specifies. Les arguments specifiques a BotBrowser (--bot-profile, --bot-config-*, etc.) sont passes via le tableau args et traites par le binaire BotBrowser lors de l'initialisation.

Le processus de lancement :

1. Playwright appelle l'executable BotBrowser avec les arguments fournis
2. BotBrowser charge le profil specifie et applique tous les parametres d'empreinte
3. BotBrowser demarre le serveur Chrome DevTools Protocol (CDP)
4. Playwright se connecte au serveur CDP et prend le controle de l'automatisation
5. A partir de ce point, toutes les operations Playwright fonctionnent normalement

Contextes de navigateur dans Playwright

Le contexte de navigateur de Playwright est une session isolee avec ses propres cookies, stockage et cache. Chaque contexte au sein d'une instance de navigateur partage le meme profil d'empreinte (puisque le profil est charge au niveau du navigateur), mais dispose d'un etat independant.

Pour des identites d'empreinte differentes, vous lancez des instances de navigateur separees, chacune avec son propre profil. Pour plusieurs sessions partageant la meme identite, vous creez plusieurs contextes au sein d'une seule instance de navigateur.

Approches courantes et leurs limites

Utiliser les navigateurs integres de Playwright

Le Chromium inclus avec Playwright fonctionne pour l'automatisation generale mais n'offre aucun controle d'empreinte. Chaque instance a la meme empreinte (celle de la machine hote), et des indicateurs d'automatisation comme navigator.webdriver sont presents.

Utiliser des builds Chromium personnalises

Certaines equipes compilent un Chromium personnalise avec des correctifs specifiques. Cela necessite de maintenir un pipeline de compilation, de suivre les mises a jour upstream de Chromium et de gerer la distribution des binaires. BotBrowser gere tout cela, fournissant des binaires prets a l'emploi avec le controle d'empreinte integre.

Surcharges d'empreinte au niveau JavaScript

Injecter du JavaScript pour surcharger les proprietes du navigator, le rendu canvas et d'autres signaux est une approche courante. Cependant, l'injection JavaScript opere apres la creation de la page et peut etre detectee par analyse de timing, inspection de la chaine de prototypes et d'autres methodes. BotBrowser applique le controle d'empreinte au niveau du moteur, avant l'execution de tout JavaScript.

L'approche de BotBrowser

BotBrowser s'integre avec Playwright via le parametre standard executablePath. Aucun plugin Playwright, correctif ou API speciale n'est necessaire.

Integration minimale

L'integration la plus simple necessite trois choses :

1. playwright-core installe (pas playwright)
2. Le chemin vers le binaire BotBrowser
3. Un fichier de profil d'empreinte

Tout le reste est du code Playwright standard.

Controle au niveau du moteur

Parce que BotBrowser modifie le moteur Chromium lui-meme, tout le controle d'empreinte se fait avant que Playwright ne se connecte. Au moment ou votre script Playwright commence a s'executer, le navigateur a deja son identite d'empreinte complete. Cela signifie :

• Les signaux d'empreinte sont presents des le premier chargement de page
• Aucune phase de "configuration" n'est necessaire dans votre code d'automatisation
• Toutes les fonctionnalites de Playwright (contextes, pages, interception reseau) fonctionnent comme documente

Configuration et utilisation

Prerequis

• Binaire BotBrowser (telecharger depuis GitHub)
• Un fichier de profil d'empreinte (format .enc)
• Node.js 18+
• npm install playwright-core

Assurez-vous que le binaire BotBrowser a les permissions d'execution :

chmod +x /path/to/botbrowser/chrome

Lancement de base

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
    ],
    headless: true,
  });

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

  // Votre logique d'automatisation ici
  const title = await page.title();
  console.log('Page title:', title);

  await browser.close();
})();

Profil + Proxy + Locale

const browser = await chromium.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
    '--proxy-server=socks5://user:pass@proxy:1080',
    '--bot-config-timezone=America/New_York',
    '--bot-config-locale=en-US',
    '--bot-config-languages=en-US,en',
  ],
  headless: true,
});

Contextes multiples (meme identite)

const browser = await chromium.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
  ],
  headless: true,
});

// Deux sessions isolees partageant la meme empreinte
const context1 = await browser.newContext();
const context2 = await browser.newContext();

const page1 = await context1.newPage();
const page2 = await context2.newPage();

await page1.goto('https://example.com');
await page2.goto('https://example.org');

// Chaque contexte a des cookies et un stockage independants
// Les deux partagent le meme profil d'empreinte

Identites multiples (navigateurs separes)

async function createIdentity(profilePath, proxyUrl) {
  const args = [
    `--bot-profile=${profilePath}`,
  ];
  if (proxyUrl) args.push(`--proxy-server=${proxyUrl}`);

  return chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args,
    headless: true,
  });
}

const identity1 = await createIdentity(
  '/profiles/win11-us.enc',
  'socks5://user:pass@us-proxy:1080'
);
const identity2 = await createIdentity(
  '/profiles/win11-de.enc',
  'socks5://user:pass@de-proxy:1080'
);

// Chaque instance de navigateur a une empreinte unique

Interception reseau

const context = await browser.newContext();
const page = await context.newPage();

// Intercepter les requetes - fonctionne comme avec Playwright standard
await page.route('**/*.png', route => route.abort());
await page.route('**/api/**', route => {
  console.log('API request:', route.request().url());
  route.continue();
});

await page.goto('https://example.com');

Gestion du viewport

// Option 1 : Laisser le profil controler le viewport (recommande)
const browser = await chromium.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
  ],
  headless: true,
});
const context = await browser.newContext(); // Pas de surcharge du viewport

// Option 2 : Viewport explicite (peut entrer en conflit avec les profils mobiles)
const context2 = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
});

Captures d'ecran et PDF

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

// Capture d'ecran - fonctionne normalement
await page.screenshot({ path: 'screenshot.png', fullPage: true });

// Generation de PDF
await page.pdf({ path: 'page.pdf', format: 'A4' });

Verification

Verifiez que l'integration fonctionne en controlant les signaux d'empreinte :

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

const fingerprint = await page.evaluate(() => ({
  userAgent: navigator.userAgent,
  platform: navigator.platform,
  languages: navigator.languages,
  hardwareConcurrency: navigator.hardwareConcurrency,
  deviceMemory: navigator.deviceMemory,
  webdriver: navigator.webdriver,
  maxTouchPoints: navigator.maxTouchPoints,
  screenWidth: screen.width,
  screenHeight: screen.height,
  dpr: devicePixelRatio,
}));

console.log('Browser fingerprint:', JSON.stringify(fingerprint, null, 2));

Bonnes pratiques

• Utilisez playwright-core, pas le package playwright complet. Le package complet telecharge son propre Chromium, dont vous n'avez pas besoin.
• Utilisez des chemins absolus pour --bot-profile. Les chemins relatifs peuvent etre resolus incorrectement selon le repertoire de travail.
• Ne definissez pas le viewport sur les contextes de navigateur sauf si vous avez specifiquement besoin de surcharger le viewport du profil. Laissez le profil controler les dimensions d'affichage.
• Definissez DISPLAY=:10.0 lorsque vous executez sur des serveurs Linux, meme en mode headless.
• Utilisez des instances de navigateur separees pour des identites separees. Les contextes de navigateur partagent la meme empreinte. Pour des identites differentes, lancez des navigateurs differents.
• Fermez les navigateurs lorsque vous avez termine. Chaque instance de navigateur est un processus Chrome. Les instances non fermees consomment de la memoire et du CPU.
• Gerez les erreurs de lancement. Verifiez que le chemin du binaire est correct et que le binaire a les permissions d'execution si le lancement echoue.

Questions frequentes

Puis-je utiliser le package playwright complet au lieu de playwright-core ?

Techniquement oui, mais il telecharger un binaire Chromium inutile. Utilisez playwright-core pour eviter le telechargement supplementaire et indiquer clairement que vous utilisez un binaire de navigateur personnalise.

Dois-je desactiver navigator.webdriver ?

BotBrowser gere le controle des signaux d'automatisation via le profil. Vous n'avez pas besoin d'ajouter du JavaScript pour modifier navigator.webdriver ou d'autres indicateurs d'automatisation.

Puis-je utiliser le codegen ou l'inspector de Playwright avec BotBrowser ?

Oui. L'outil codegen de Playwright fonctionne avec BotBrowser lorsque vous specifiez le chemin de l'executable. Lancez npx playwright codegen --browser-channel=chromium et configurez l'executable personnalise dans votre configuration Playwright.

Comment executer BotBrowser avec Playwright sur Ubuntu ?

Definissez la variable d'environnement DISPLAY et installez les bibliotheques requises :

export DISPLAY=:10.0
# Installer les dependances si necessaire
apt-get install -y libnss3 libatk-bridge2.0-0 libdrm2 libxrandr2 libgbm1

Puis-je utiliser le proxy par contexte de Playwright avec BotBrowser ?

BotBrowser supporte le proxy par contexte via son propre mecanisme. L'utilisation de --proxy-server definit le proxy au niveau du navigateur. Pour le proxy par contexte, utilisez la fonctionnalite d'empreinte par contexte de BotBrowser (ENT Tier1), qui derive automatiquement les informations geographiques. Evitez page.authenticate() de Playwright pour l'authentification proxy, car cela peut interferer avec la detection geographique de BotBrowser.

Combien d'instances de navigateur concurrentes puis-je executer ?

Cela depend de vos ressources systeme. Chaque instance BotBrowser est un processus Chrome qui utilise generalement 200-500 Mo de RAM. Un serveur avec 32 Go de RAM peut confortablement executer 30-60 instances concurrentes, selon la complexite des pages.

Le tracing et le debogage de Playwright fonctionnent-ils avec BotBrowser ?

Oui. Le visualiseur de traces de Playwright (context.tracing.start()), les captures d'ecran et l'enregistrement video fonctionnent tous normalement avec BotBrowser.

Puis-je utiliser TypeScript avec playwright-core ?

Oui. playwright-core inclut les definitions de types TypeScript. Utilisez-le de la meme maniere que Playwright standard avec TypeScript :

import { chromium, Browser, Page } from 'playwright-core';

Resume

L'integration de BotBrowser avec Playwright necessite des changements minimaux par rapport au code Playwright standard : installez playwright-core, pointez executablePath vers le binaire BotBrowser et ajoutez --bot-profile aux arguments de lancement. Tout le reste (interactions de page, interception reseau, captures d'ecran, assertions) fonctionne exactement comme documente dans l'API de Playwright.

Pour des sujets connexes, consultez Premiers pas avec Puppeteer pour l'equivalent Puppeteer, Recettes CLI pour plus de combinaisons de flags, et Gestion des profils pour l'organisation des profils.