Playwright avec des profils d'identité cohérents

Playwright peut piloter un exécutable BotBrowser avec une identité fondée sur un profil, mais il ne garantit pas l'acceptation d'un site tiers et ne remplace pas les contrôles de compte ou de confidentialité de l'application.

TL;DR

• Utilisez playwright-core avec l'exécutable BotBrowser et un profil approuvé, sans télécharger de navigateur intégré.
• Gardez le profil, la route, la paire de versions, le cycle de vie du contexte et la preuve de nettoyage dans la même unité.
• Validez une session avant d'augmenter la concurrence et conservez les résultats opérationnels sans collecter le contenu des pages par défaut.

Contents

• Comment Playwright et BotBrowser s'articulent
• Lancement, contextes et vérifications de l'application
• Validation et paire de versions
• Responsabilités, cohérence réseau et télémétrie
• Déploiement, retour arrière et dépannage
• Conclusion pratique

Comment Playwright et BotBrowser s'articulent

Playwright fournit l'automatisation du navigateur, des attentes fiables et une API claire pour les parcours de page. BotBrowser ajoute une identité de navigateur fondée sur un profil, pour des travaux autorisés de confidentialité et de compatibilité. Playwright reste responsable de la navigation et de l'interaction, tandis que le profil sélectionné gouverne l'identité présentée par le navigateur.

L'intégration commence au lancement. L'installation, la politique de proxy, la propriété des contextes, le viewport et le cycle de vie des processus doivent décrire le même déploiement. Les exemples ci-dessous reposent sur des usages pris en charge de Playwright et signalent les points à vérifier avec les versions exécutées en production.

L'automatisation standard d'un navigateur peut exposer des caractéristiques de l'hôte situées hors du périmètre de confidentialité prévu. Un navigateur fondé sur un profil permet à un déploiement autorisé de maîtriser cette exposition et de garder alignées les caractéristiques associées pendant toute la session.

Playwright gère la navigation, les vérifications de l'application et la logique d'interaction. BotBrowser maintient l'identité de la famille de navigateur sélectionnée. Cette séparation garde la configuration de confidentialité hors des scripts de page et donne aux exploitants une seule affectation de profil relue, à suivre avec chaque processus du navigateur ou chaque parcours de contexte pris en charge. Les sélecteurs, les assertions et l'interception réseau continuent d'utiliser les API de Playwright.

Pourquoi playwright-core et non playwright

Le paquet npm standard playwright embarque son propre binaire Chromium et télécharge automatiquement les binaires de navigateur. C'est pratique pour un usage général, mais cela entre en conflit avec BotBrowser, qui fournit son propre binaire Chromium modifié.

Le paquet playwright-core offre la même API sans navigateurs embarqués. Il exige un executablePath au lancement, ce qui est précisément la façon de pointer Playwright vers le binaire BotBrowser.

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

Gardez une configuration de lancement réduite

Faites pointer playwright-core vers l'exécutable BotBrowser et affectez le profil approuvé avant d'ouvrir une page. Gardez visibles dans la configuration du déploiement la version, le profil et le mode du navigateur. Une surface de lancement réduite se relit, se reproduit et se rétablit plus facilement.

N'ajoutez des options que lorsque l'application a une exigence documentée pour elles. Conservez les secrets dans le circuit de gestion des secrets du déploiement. Enregistrez les versions de BotBrowser et de Playwright avec le résultat du travail afin que le support puisse reproduire la même paire de versions.

Contextes de navigateur dans Playwright

Un contexte de navigateur Playwright est une frontière de session pour les cookies, le stockage, les permissions et le cache. Utilisez-le pour séparer des comptes de test autorisés et des états d'application. Désignez un responsable clair pour chaque contexte et fermez-le à la fin du test.

L'affectation du profil dépend du parcours BotBrowser pris en charge. Appliquez l'affectation approuvée avant que le contexte n'ouvre sa première page, puis gardez-la stable pendant toute la durée de vie du contexte.

Alternatives et leurs limites

Navigateur embarqué. Le navigateur embarqué de Playwright convient à l'automatisation générale, mais il ne charge pas de paquet de profil BotBrowser. Utilisez playwright-core pour que la bibliothèque d'automatisation se connecte au binaire BotBrowser choisi pour le déploiement.

Modifications au niveau de la page. Un script de page peut changer des valeurs isolées après la navigation, mais il ne produit pas une identité de navigateur cohérente entre le démarrage, les workers, le rendu graphique, les médias et le réseau. Gardez la configuration d'identité dans le profil du navigateur plutôt que d'ajouter des scripts de page.

Builds personnalisés. Maintenir un build Chromium privé demande de suivre les versions, de produire des paquets et de les distribuer par plateforme. BotBrowser fournit des binaires versionnés et des paquets de profil correspondants, pour que l'application se concentre sur le parcours Playwright.

Lancement, contextes et vérifications de l'application

Prérequis

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

Vérifiez que le binaire BotBrowser dispose du droit d'exécution :

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=/absolute/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 va ici
  const title = await page.title();
  console.log('Page title:', title);

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

Profil, route réseau et paramètres régionaux

Relisez la famille du profil, la route réseau approuvée, les paramètres régionaux, le fuseau horaire et le compte de l'application comme une seule décision de déploiement. Leurs hypothèses régionales doivent concorder. Transmettez la route avec --proxy-server dans args plutôt qu'avec les options de proxy propres à Playwright, et utilisez un chemin absolu pour --bot-profile.

Fournissez les identifiants par le coffre de secrets du déploiement et gardez-les hors des traces, des captures et de la sortie du terminal. Le même lancement peut porter --bot-timezone, --bot-locale et --bot-languages lorsque le test autorisé exige une région précise.

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/absolute/path/to/profile.enc',
    // Fournissez la route depuis le coffre de secrets du déploiement
    `--proxy-server=${process.env.BOT_PROXY_URL}`,
    '--bot-timezone=Europe/Berlin',
    '--bot-locale=de-DE',
    '--bot-languages=de-DE,de,en-US,en',
  ],
  headless: true,
});

Vérification de l'isolation des sessions

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

const context1 = await browser.newContext();
const context2 = await browser.newContext();

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

await page1.goto('https://staging.example.test/account-a');
await page2.goto('https://staging.example.test/account-b');

// Exécutez les assertions habituelles de l'application pour chaque compte de test autorisé.
await context1.close();
await context2.close();

La vérification doit s'appuyer sur votre propre application de préproduction et sur les assertions habituelles du produit. Confirmez que la connexion, la déconnexion, le nettoyage du stockage, l'annulation et la fermeture du contexte se comportent comme l'exige le plan de test. Ne collectez ni signaux du navigateur ni données de page dont le test de l'application n'a pas besoin.

Interception réseau

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

// Interceptez les requêtes avec l'API Playwright habituelle
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 : laissez le profil contrôler le viewport (recommandé)
const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: ['--bot-profile=/absolute/path/to/profile.enc'],
  headless: true,
});
const context = await browser.newContext(); // Aucun viewport imposé

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

Les profils mobiles doivent conserver le viewport fourni par le profil. BotBrowser 150.0.7871.46 garde le visual viewport aligné lorsqu'un clavier logiciel modifie la zone visible de la page. Évitez de forcer le viewport depuis Playwright, sauf si le test exige explicitement d'autres dimensions.

Captures d'écran et PDF

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

// Capturez un artefact exigé par le plan de test autorisé.
await page.screenshot({ path: 'screenshot.png', fullPage: true });

// Génération de PDF
await page.pdf({ path: 'page.pdf', format: 'A4' });

Validation et paire de versions

Commencez par une session de préproduction autorisée. Confirmez que le navigateur démarre, que la première navigation aboutit, que les captures se terminent et que le navigateur se ferme sans erreur de profil ni de processus. Répétez avec le même profil et la même route pour que la référence reste comparable.

Pour l'automatisation par lots, enregistrez les erreurs de lancement, le statut de sortie du navigateur et le stderr de chaque worker. Gardez fixes la version du binaire, le paquet de profil, la politique de proxy et la politique de viewport pendant la validation d'un changement d'intégration.

Lancements headless et validation du profil

BotBrowser 150.0.7871.46 signale par la sortie du terminal les profils manquants, invalides, expirés ou d'une autre version pendant un lancement headless. Chargez un paquet de profil correspondant avant de naviguer et traitez un échec de validation du profil comme un démarrage de worker en échec.

Utilisez un répertoire de données utilisateur distinct pour chaque processus du navigateur et conservez le stderr de chaque worker. Commencez avec un petit groupe, confirmez que les pages avec profil s'ouvrent normalement, puis augmentez le parallélisme avec une file bornée. Fermez les pages, les contextes et le navigateur sur tous les chemins de sortie.

Gardez la paire de versions explicite

Enregistrez ensemble la version de BotBrowser et celle du paquet Playwright. Les bibliothèques d'automatisation évoluent avec les protocoles du navigateur, et un parcours stable avec une paire de versions ne doit pas être supposé identique après un changement de l'un ou l'autre côté. Figez les deux versions dans le fichier de verrouillage de l'application ou dans le manifeste du déploiement, puis mettez-les à jour avec la même relecture que pour les autres dépendances de production.

Une vérification de version doit utiliser des pages représentatives appartenant à l'équipe ou explicitement autorisées pour les tests. Confirmez la navigation normale, les interactions nécessaires, les assertions de l'application, les captures ou documents utilisés par le travail et l'arrêt ordonné. N'incluez les modes headless et avec interface que si les deux font partie du déploiement. Un mode qui n'est jamais livré n'a pas à élargir la matrice de test.

Traitez le paquet de profil, le binaire du navigateur, le paquet d'automatisation et l'image du système d'exploitation comme une seule unité de version traçable. Si l'application s'exécute dans des conteneurs, enregistrez aussi la révision de l'image. Un résultat inattendu devient ainsi reproductible sans collecter de données de page étrangères à l'intégration.

Relire une paire de versions candidate

Préparez la candidate sur la même classe d'hôte que celle du déploiement. Restaurez le fichier de verrouillage des dépendances, installez la version choisie de BotBrowser et utilisez le paquet de profil approuvé pour cette version. Avant de démarrer la session, confirmez que le chemin de l'exécutable, le mode de lancement, la politique de route et la configuration de l'application correspondent au dossier de version. Un résultat obtenu sur un ordinateur portable de développement est utile pendant la préparation, mais ne remplace pas une vérification dans l'environnement d'exploitation visé.

Exécutez la candidate sur un ensemble stable de pages appartenant à l'équipe. Gardez inchangés le compte de test, les données de l'application, la route et les assertions attendues. Comparez des résultats visibles par l'utilisateur, comme la navigation réussie, les actions de formulaire terminées, les documents générés et l'arrêt ordonné. Si un résultat attendu change, conservez la paire précédente le temps d'examiner la différence. Évitez de changer en une seule étape le navigateur, le paquet Playwright, le paquet de profil et le code de l'application, car les éléments recueillis n'indiqueraient pas quel composant de la version demande de l'attention.

Réaliser un contrôle de qualité sur une seule session

Utilisez sessionId pour délimiter ce contrôle.

Commencez par une session et un compte approuvé. Vérifiez comme un seul cycle de vie le démarrage, la première page nécessaire, l'action de l'application, le nettoyage et la sortie du navigateur. Avant de fermer le contexte, confirmez que le test n'a créé que les cookies, le stockage, les permissions et les fichiers attendus par l'application. Après la fermeture, démarrez une nouvelle session et confirmez que l'état du compte précédent a disparu, sauf si la persistance est une exigence explicite.

Exercez aussi l'annulation et l'échec de l'application, pas seulement le chemin réussi. Un travail annulé doit arrêter toute nouvelle activité de page, fermer son contexte et libérer le navigateur selon la politique. Un échec d'assertion de l'application doit conserver le dossier opérationnel minimal tout en suivant le même chemin de nettoyage. Ce contrôle donne à l'équipe une frontière de session fiable avant de mettre plus de travail en file ou d'évaluer la capacité.

Conserver les preuves de reprise

Gardez un dossier de version compact pour chaque paire acceptée. Indiquez la version du navigateur, celle du paquet Playwright, la famille du paquet de profil, l'image du système d'exploitation, le groupe de déploiement, la date de validation et le résultat final. Notez si le démarrage, le parcours représentatif de l'application, le nettoyage de l'état, l'annulation et l'arrêt ont réussi. Référencez la révision du test de l'application pour qu'un autre exploitant puisse répéter la même vérification approuvée.

Lorsqu'une candidate est rejetée, consignez la première frontière du cycle de vie qui n'a pas abouti et l'unité de version rétablie. Confirmez la paire rétablie avec la même vérification sur une seule session avant de rouvrir la file. Ces éléments montrent ce qui a été déployé, ce que l'application a observé et quelle version connue a ramené le service à son état relu.

Responsabilités, cohérence réseau et télémétrie

Propriété des processus et des contextes

Utilisez browserProcessId et contextId comme ancrages du cycle de vie.

Chaque processus du navigateur a besoin d'un responsable dans le cycle de vie de l'application. Ce responsable le crée, lui affecte le profil approuvé et la politique de route, observe le démarrage et le ferme après un succès, une annulation ou une erreur. Un utilitaire partagé peut imposer ce cycle de vie, mais le code de l'application doit attendre la fin du nettoyage avant de déclarer un travail terminé.

Les contextes de navigateur ont eux aussi besoin d'un responsable clair. Utilisez un contexte pour une frontière définie de stockage et de session, puis fermez-le à la fin de ce travail. Ne remettez pas un contexte dans un pool général, sauf si le travail suivant est explicitement autorisé à hériter de son stockage, de ses permissions et de son affectation de profil. Pour un travail sensible à la confidentialité, une frontière neuve est généralement plus facile à relire qu'un contexte durable aux responsabilités changeantes.

Les chemins d'annulation méritent la même attention que les chemins réussis. Lorsqu'un élément de la file expire ou qu'un appelant se déconnecte, arrêtez le travail sur de nouvelles pages, fermez le contexte actif et libérez le navigateur selon la politique du déploiement. Consignez si le nettoyage s'est terminé. Une annulation silencieuse qui laisse des processus du navigateur actifs finira par apparaître sous forme de pression mémoire ou de réutilisation inexpliquée de profils.

Cohérence entre proxy et profil

Enregistrez la décision réseau révisée sous routePolicy.

Traitez l'affectation du profil et la route réseau comme une seule décision relue. Les paramètres régionaux, le fuseau horaire, les réglages régionaux et la région du proxy doivent décrire le même environnement autorisé. Gardez le choix de la route dans le parcours pris en charge du navigateur ou du déploiement plutôt que de le répartir entre le code de page et plusieurs gestionnaires externes.

Lorsque les identifiants tournent, conservez le profil et l'ensemble de pages pendant la validation de la nouvelle route. Lorsqu'un paquet de profil change, conservez la route approuvée pendant la validation du nouveau paquet. Changer les deux à la fois complique le classement d'un échec. Après chaque changement, répétez les vérifications ordinaires de l'application et n'enregistrez que les identifiants de version et le résultat utiles au support.

N'écrivez pas les identifiants du proxy dans la sortie de console, les traces, les captures ou les métadonnées de travail. Fournissez-les par le circuit de gestion des secrets du déploiement et limitez l'accès aux comptes de service qui lancent le parcours autorisé. Vérifiez le masquage dans le journaliseur de l'application avant d'activer le tracing Playwright en production.

Observabilité sans collecte de pages

Conservez firstPageReadyMs et exitCode comme ancrages opérationnels, sans contenu.

La télémétrie utile à l'intégration est surtout opérationnelle. Enregistrez la fin du démarrage du navigateur, la disponibilité de la première page, la durée de la tâche, la fermeture du contexte, le statut de sortie du navigateur, le délai de file et les identifiants de version. Ces observations montrent si le système est sain sans conserver de contenu de page ni d'historique de navigation détaillé.

Les captures, les vidéos, les traces et les archives réseau peuvent contenir des données de compte ou un état privé de l'application. Activez-les uniquement pour un dossier de support approuvé ou pour un parcours qui les exige déjà. Appliquez des contrôles d'accès et des limites de conservation avant le début de la collecte. Désactivez les diagnostics temporaires une fois le problème résolu.

Agrégez les données de capacité par groupe de déploiement au lieu de rattacher une activité détaillée du navigateur à une session individuelle. La tendance de la mémoire, la saturation du processeur, les sorties du navigateur et les travaux terminés suffisent à la plupart des décisions de dimensionnement. Séparez la revue de confidentialité de la revue de performance lorsque leurs éléments ont des durées de conservation différentes.

Déploiement, retour arrière et dépannage

Mises à jour et retour arrière

Regroupez le déploiement sous un deploymentGroup traçable.

Déployez d'abord une nouvelle version du navigateur ou de Playwright sur un petit groupe. Comparez-la à un groupe inchangé qui utilise la même charge, la même famille de profil, la même politique de route et la même classe d'hôte. Faites une pause lorsque les assertions de l'application, la stabilité du navigateur ou les résultats de nettoyage s'écartent du plan de version. Rétablissez la paire précédente avant de tester un second changement.

Le paquet de retour arrière doit inclure l'ancien binaire du navigateur, le verrouillage des dépendances d'automatisation, un paquet de profil compatible et la configuration du déploiement. Testez ce paquet tant qu'il est encore d'actualité. Une consigne de retour arrière ne sert à rien si son binaire a été retiré ou si son paquet de profil a expiré.

Après un déploiement réussi, retirez les anciens paquets selon la politique de conservation de l'organisation. Gardez seulement le dossier de version utile au support : paire de versions, famille de profil, groupe de déploiement, fenêtre de validation et résultat. Évitez de conserver des traces complètes uniquement parce qu'elles ont été collectées en préproduction.

Traiter les problèmes de lancement et d'exécution

Classez la première limite échouée avec le champ failureBoundary.

Classez un travail en échec selon la première frontière visible par l'utilisateur qui n'a pas abouti. Un échec de lancement, de validation du profil, de première navigation, d'assertion de l'application ou d'arrêt relève de responsables différents. Conservez la sortie normale du terminal et le statut de sortie, puis comparez l'unité de version affectée à celle du dernier travail réussi.

Revenez à la dernière paire de versions qui fonctionnait avant de modifier plusieurs réglages. Confirmez l'accès au binaire, l'affectation du profil, la disponibilité de la route et les ressources de l'hôte grâce aux vérifications ordinaires du déploiement. Une fois la référence rétablie, introduisez un seul changement et répétez le parcours représentatif de l'application.

Ne transformez pas un incident de production en inspection de pages sans limite. Le dossier de support doit contenir le groupe de déploiement concerné, le résultat observable, les identifiants de version, l'action corrective et la validation finale. Ne collectez des éléments de page supplémentaires que si le responsable de l'application l'autorise et que les éléments opérationnels habituels ne suffisent pas.

Liste de contrôle pour la production

• Utilisez playwright-core, pas le paquet complet playwright. Le paquet complet télécharge son propre Chromium, dont vous n'avez pas besoin.
• Utilisez des chemins absolus pour --bot-profile. Les chemins relatifs peuvent être mal résolus selon le répertoire de travail.
• Ne définissez pas de viewport sur les contextes du navigateur, sauf si vous devez remplacer celui du profil. Laissez le profil contrôler les dimensions d'affichage.
• Définissez DISPLAY=:10.0 sur les serveurs Linux, même en mode headless.
• Gardez la propriété du profil explicite. Utilisez uniquement l'affectation de profil prise en charge par le parcours BotBrowser choisi et appliquez-la avant la première page.
• Fermez les navigateurs après usage. Un travail de navigateur non fermé continue de consommer la capacité de l'hôte.
• Gérez les erreurs de lancement. Si le lancement échoue, vérifiez que le chemin du binaire est correct et que le binaire a le droit d'exécution.

Questions fréquentes

• Puis-je utiliser le paquet Playwright complet ? Oui, mais il télécharge un autre navigateur dont cette configuration n'a pas besoin. playwright-core garde la bibliothèque d'automatisation séparée du binaire BotBrowser.
• Ai-je besoin de scripts de page pour l'identité ? Non. Chargez un paquet de profil correspondant au démarrage du navigateur ou appliquez le profil par contexte pris en charge avant le démarrage de la première cible.
• Puis-je utiliser Playwright codegen ou l'inspecteur ? Utilisez les outils de développement Playwright avec le même exécutable personnalisé et la même configuration de profil que le projet. Gardez alignées les versions de profil de développement et de production.
• Comment l'exécuter sur Ubuntu ? Installez les bibliothèques d'exécution exigées par la version choisie et suivez le guide Headless Server Setup. Choisissez le chemin graphique avec le guide Linux GPU Backend.
• Puis-je utiliser un proxy par contexte ? Oui. Les parcours de proxy Context et Live de BotBrowser exigent ENT Tier3. Appliquez le proxy et le profil avant le démarrage de la première page ou du premier worker, et gardez l'authentification au niveau du framework en dehors de cette route.
• Combien de workers puis-je exécuter ? Mesurez des pages représentatives sur l'hôte cible. Utilisez une file bornée, gardez une marge de mémoire et vérifiez l'arrêt complet avant d'augmenter la concurrence.
• Le tracing et les captures fonctionnent-ils ? Playwright propose les deux fonctions lorsque la paire de versions choisie et l'environnement d'exploitation les prennent en charge. Confirmez les artefacts dont l'application a besoin, appliquez des contrôles d'accès et de conservation, et incluez leur coût en ressources dans les mesures de capacité.
• Puis-je utiliser TypeScript ? Oui. playwright-core inclut les définitions TypeScript.

Conclusion pratique

Utilisez playwright-core pour séparer l'automatisation de l'exécutable BotBrowser, affectez le profil approuvé avant la première page et traitez la route, la version, le nettoyage du contexte et la télémétrie comme un seul parcours révisé. Vous obtenez ainsi une limite de lancement répétable sans revendiquer le contrôle d'une application tierce.

Ce que BotBrowser couvre dans ce parcours

BotBrowser prend en charge le lancement par l'executablePath standard de Playwright avec --bot-profile et un --proxy-server facultatif, de sorte que le profil sélectionné gouverne l'identité du navigateur pendant que Playwright continue de gérer la navigation, les contextes et les assertions dans la même configuration de lancement reproductible. Pour cette configuration, cela donne une définition de lancement relue qu'une équipe peut figer, répéter et rétablir comme une unité de version. BotBrowser ne remplace pas l'API d'automatisation de Playwright, ne garantit aucun résultat sur un site tiers et ne peut pas contrôler l'application testée, le fournisseur du proxy ni l'état du compte. Les parcours Per-Context et de proxy Live exigent en outre ENT Tier3.

Installez playwright-core, faites pointer executablePath vers le binaire BotBrowser et affectez le profil approuvé au lancement. Validez la paire de versions exacte sous la charge prévue avant le déploiement. Téléchargez BotBrowser ou consultez les offres tarifaires pour le parcours concerné.

Pour des sujets voisins, consultez Premiers pas avec Puppeteer pour l'équivalent avec Puppeteer, Recettes CLI pour d'autres combinaisons d'options, Gestion des profils pour organiser les profils et Proxy par contexte pour la propriété des routes entre contextes séparés.

Pour les quatre surfaces qu'une première exécution doit couvrir, commencez par la carte des premiers pas.

Sources publiques

• BotBrowser sur GitHub
• Guide BotBrowser pour Playwright
• API BrowserType de Playwright