Playwright и согласованные профили идентичности браузера

Playwright может управлять исполняемым файлом BotBrowser с идентичностью из профиля, но не гарантирует приём со стороны стороннего сайта и не заменяет собственные средства контроля аккаунта и приватности приложения.

TL;DR

• Используйте playwright-core с исполняемым файлом BotBrowser и утверждённым профилем вместо загрузки встроенного браузера.
• Храните профиль, маршрут, пару версий, жизненный цикл контекста и запись очистки как одну проверяемую единицу.
• Проверьте один сеанс до увеличения параллельности и по умолчанию сохраняйте операционные итоги без содержимого страниц.

Contents

• Как Playwright и BotBrowser работают вместе
• Запуск, контексты и проверки приложения
• Проверка и пара версий
• Владение, сетевая согласованность и телеметрия
• Выпуск, откат и разбор проблем
• Заключение

Как Playwright и BotBrowser работают вместе

Playwright предоставляет автоматизацию браузера, надёжные ожидания и понятный API для сценариев работы со страницами. BotBrowser добавляет идентичность браузера на основе профиля для разрешённых задач по приватности и совместимости. Playwright по-прежнему отвечает за навигацию и взаимодействие, а выбранный профиль определяет идентичность, которую предъявляет браузер.

Интеграция начинается с запуска. Установка, политика прокси, владение контекстами, размеры viewport и жизненный цикл процессов должны описывать одно и то же развёртывание. В примерах ниже используются поддерживаемые сценарии Playwright, а моменты, которые нужно сверить с версиями в продакшене, отмечены отдельно.

Стандартная автоматизация браузера может раскрывать характеристики хоста, которые выходят за намеченные границы приватности. Браузер на основе профиля позволяет разрешённому развёртыванию управлять этим раскрытием и сохранять согласованность связанных характеристик на протяжении всего сеанса.

Playwright отвечает за навигацию, проверки приложения и логику взаимодействия. BotBrowser поддерживает идентичность выбранного семейства браузеров. Такое разделение оставляет настройку приватности вне скриптов страницы и даёт операторам одно проверенное назначение профиля, которое можно отслеживать вместе с каждым процессом браузера или поддерживаемым сценарием контекста. Селекторы, проверки и перехват сетевых запросов по-прежнему выполняются через API Playwright.

Почему playwright-core, а не playwright

Стандартный npm-пакет playwright включает собственный бинарный файл Chromium и автоматически скачивает браузеры. Это удобно для общих задач, но конфликтует с BotBrowser, который поставляется со своим изменённым бинарным файлом Chromium.

Пакет playwright-core предоставляет тот же API без встроенных браузеров. При запуске ему нужен executablePath, и именно так Playwright направляется на бинарный файл BotBrowser.

# Установите playwright-core, а не playwright
npm install playwright-core

Держите конфигурацию запуска небольшой

Укажите playwright-core исполняемый файл BotBrowser и назначьте утверждённый профиль до открытия страницы. Храните выбор версии, профиля и режима браузера на виду в конфигурации развёртывания. Небольшую конфигурацию запуска проще проверять, воспроизводить и откатывать.

Добавляйте параметры только тогда, когда у приложения есть документированная потребность в них. Храните секреты в принятом для развёртывания хранилище секретов. Записывайте версии BotBrowser и Playwright вместе с результатом задания, чтобы поддержка могла воспроизвести ту же пару версий.

Контексты браузера в Playwright

Контекст браузера Playwright задаёт границу сеанса для cookie, хранилища, разрешений и кэша. Используйте его, чтобы разделять разрешённые тестовые учётные записи и состояния приложения. Назначьте каждому контексту понятного владельца и закрывайте его, когда тест завершён.

Назначение профиля зависит от используемого поддерживаемого сценария BotBrowser. Примените утверждённое назначение до того, как контекст откроет первую страницу, и сохраняйте его неизменным всё время жизни контекста.

Альтернативы и их ограничения

Встроенный браузер. Встроенный браузер Playwright подходит для общей автоматизации, но не загружает пакет профиля BotBrowser. Используйте playwright-core, чтобы библиотека автоматизации подключалась к бинарному файлу BotBrowser, выбранному для развёртывания.

Изменения на уровне страницы. Скрипты страницы могут менять отдельные значения после навигации, но не создают согласованную идентичность браузера на этапах запуска, в воркерах, графике, медиа и сетевом поведении. Держите настройку идентичности в профиле браузера, а не добавляйте скрипты на страницу.

Собственные сборки. Поддержка частной сборки Chromium требует отслеживать выпуски, готовить пакеты и распространять их по платформам. BotBrowser предоставляет версионированные бинарные файлы и соответствующие пакеты профилей, чтобы приложение могло сосредоточиться на сценарии Playwright.

Запуск, контексты и проверки приложения

Предварительные требования

• Бинарный файл BotBrowser (скачать с GitHub)
• Файл профиля отпечатка (формат .enc)
• Node.js 18+
• npm install playwright-core

Убедитесь, что у бинарного файла BotBrowser есть право на выполнение:

chmod +x path/to/botbrowser/chrome

Базовый запуск

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');

  // Здесь размещается ваша логика автоматизации
  const title = await page.title();
  console.log('Page title:', title);

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

Профиль, сетевой маршрут и региональные параметры

Рассматривайте семейство профиля, утверждённый сетевой маршрут, язык и региональные параметры, часовой пояс и учётную запись приложения как одно решение о развёртывании. Их региональные предположения должны совпадать. Передавайте маршрут через --proxy-server в args, а не через собственные параметры прокси Playwright, и указывайте для --bot-profile абсолютный путь.

Передавайте учётные данные через хранилище секретов развёртывания и не допускайте их попадания в трассировки, снимки экрана и вывод терминала. В тот же запуск можно добавить --bot-timezone, --bot-locale и --bot-languages, если разрешённому тесту нужен конкретный регион.

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/absolute/path/to/profile.enc',
    // Передайте маршрут из хранилища секретов развёртывания
    `--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,
});

Проверка изоляции сеансов

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');

// Выполните обычные проверки приложения для каждой разрешённой тестовой учётной записи.
await context1.close();
await context2.close();

Для проверки используйте собственное тестовое окружение приложения и обычные продуктовые проверки. Убедитесь, что вход, выход, очистка хранилища, отмена и закрытие контекста работают так, как требует план тестирования. Не собирайте сигналы браузера и данные страниц, которые не нужны для теста приложения.

Перехват сетевых запросов

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

// Перехватывайте запросы обычным API Playwright
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');

Управление viewport

// Вариант 1: пусть размерами окна управляет профиль (рекомендуется)
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(); // Без переопределения viewport

// Вариант 2: явный viewport (может конфликтовать с мобильными профилями)
const context2 = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
});

Для мобильных профилей оставляйте viewport, который задаёт профиль. BotBrowser 150.0.7871.46 сохраняет согласованность visual viewport, когда экранная клавиатура меняет видимую область страницы. Не переопределяйте viewport средствами Playwright, если тест явно не требует других размеров.

Снимки экрана и PDF

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

// Сохраните артефакт, который требует разрешённый план тестирования.
await page.screenshot({ path: 'screenshot.png', fullPage: true });

// Создание PDF
await page.pdf({ path: 'page.pdf', format: 'A4' });

Проверка и пара версий

Начните с одного разрешённого сеанса в тестовом окружении. Убедитесь, что браузер запускается, первая навигация завершается, снимки экрана создаются, а браузер закрывается без ошибок профиля или процесса. Повторите с тем же профилем и тем же маршрутом, чтобы базовый результат оставался сопоставимым.

При пакетной автоматизации записывайте ошибки запуска, код завершения браузера и stderr каждого воркера. Пока вы проверяете изменение интеграции, не меняйте версию бинарного файла, пакет профиля, политику прокси и политику viewport.

Запуск headless и проверка профиля

BotBrowser 150.0.7871.46 сообщает через вывод терминала об отсутствующих, недействительных, просроченных или несовпадающих по версии профилях во время запуска headless. Загружайте соответствующий пакет профиля до навигации и считайте ошибку проверки профиля неудачным запуском воркера.

Используйте отдельный каталог пользовательских данных для каждого процесса браузера и сохраняйте stderr каждого воркера. Начните с небольшой группы, убедитесь, что страницы с профилем открываются нормально, и только затем увеличивайте параллелизм с помощью ограниченной очереди. Закрывайте страницы, контексты и браузер на любом пути завершения.

Зафиксируйте пару версий явно

Записывайте версию BotBrowser и версию пакета Playwright вместе. Библиотеки автоматизации развиваются вместе с протоколами браузера, поэтому сценарий, стабильный с одной парой версий, нельзя считать одинаковым после изменения любой из сторон. Закрепите обе версии в файле блокировки зависимостей приложения или в манифесте развёртывания и обновляйте их тем же порядком проверки, что и остальные зависимости продакшена.

Для проверки выпуска используйте репрезентативные страницы, которые принадлежат команде или явно разрешены для тестирования. Проверьте обычную навигацию, необходимые действия, проверки приложения, снимки экрана или документы, которые использует задание, и корректное завершение. Включайте режимы headless и с интерфейсом только тогда, когда оба входят в развёртывание. Режим, который никогда не поставляется, не должен расширять матрицу проверки.

Рассматривайте пакет профиля, бинарный файл браузера, пакет автоматизации и образ операционной системы как одну отслеживаемую единицу выпуска. Если приложение работает в контейнерах, записывайте и ревизию образа. Так неожиданный результат можно воспроизвести без сбора данных страниц, не связанных с интеграцией.

Проверка кандидата на новую пару версий

Подготовьте кандидата на хосте того же класса, что и в развёртывании. Восстановите файл блокировки зависимостей, установите выбранную версию BotBrowser и используйте пакет профиля, утверждённый для этой версии. Перед началом сеанса убедитесь, что путь к исполняемому файлу, режим запуска, политика маршрута и конфигурация приложения совпадают с записью о выпуске. Результат на ноутбуке разработчика полезен при подготовке, но не заменяет проверку в предполагаемой рабочей среде.

Запустите кандидата на стабильном наборе страниц, принадлежащих команде. Оставьте без изменений тестовую учётную запись, данные приложения, маршрут и ожидаемые проверки. Сравнивайте результаты, видимые пользователю: успешную навигацию, завершённые действия с формами, созданные документы и корректное завершение. Если ожидаемый результат изменился, сохраняйте предыдущую пару, пока различие не будет разобрано. Не меняйте за один шаг браузер, пакет Playwright, пакет профиля и код приложения, потому что полученные данные не покажут, какой элемент выпуска требует внимания.

Проверка качества на одном сеансе

Начните с одного сеанса и одной утверждённой учётной записи. Проверьте запуск, первую нужную страницу, действие приложения, очистку и выход браузера как единый жизненный цикл. Перед закрытием контекста убедитесь, что тест создал только те cookie, данные хранилища, разрешения и файлы, которых ожидает приложение. После закрытия начните новый сеанс и убедитесь, что состояние прежней учётной записи отсутствует, если только сохранение состояния не является явным требованием.

Проверяйте не только успешный путь, но и отмену и сбой приложения. Отменённое задание должно прекратить новую активность страниц, закрыть свой контекст и освободить браузер согласно политике. Сбой проверки приложения должен сохранить минимальную рабочую запись и пройти тот же путь очистки. Такая проверка даёт команде надёжную границу сеанса до того, как в очередь поставят больше работы или начнут оценивать ёмкость.

Сохраняйте подтверждения для восстановления

Ведите компактную запись о выпуске для каждой принятой пары. Указывайте версию браузера, версию пакета Playwright, семейство пакета профиля, образ операционной системы, группу развёртывания, дату проверки и итог. Отмечайте, прошли ли запуск, типовой сценарий приложения, очистка состояния, отмена и завершение. Ссылайтесь на ревизию теста приложения, чтобы другой оператор мог повторить ту же утверждённую проверку.

Если кандидат отклонён, запишите первую границу жизненного цикла, которая не завершилась, и единицу выпуска, к которой вернулись. Подтвердите восстановленную пару той же проверкой на одном сеансе, прежде чем снова открывать очередь. Эти записи показывают, что было развёрнуто, что наблюдало приложение и какой известный выпуск вернул сервис в проверенное состояние.

Владение, сетевая согласованность и телеметрия

Владение процессами и контекстами

Используйте browserProcessId и contextId как контрольные точки жизненного цикла.

У каждого процесса браузера должен быть владелец в жизненном цикле приложения. Владелец создаёт процесс, назначает утверждённый профиль и политику маршрута, наблюдает за запуском и закрывает процесс после успеха, отмены или ошибки. Общий вспомогательный модуль может обеспечивать этот цикл, но код приложения всё равно должен дождаться очистки, прежде чем сообщить о завершении задания.

Контексты браузера тоже нуждаются в понятном владельце. Используйте контекст для определённой границы хранилища и сеанса и закрывайте его, когда эта работа завершена. Не возвращайте контекст в общий пул, если следующему заданию явно не разрешено наследовать его хранилище, разрешения и назначенный профиль. Для работы, чувствительной к приватности, новую границу обычно проще проверить, чем долгоживущий контекст с меняющимися обязанностями.

Пути отмены заслуживают такого же внимания, как и успешные. Когда элемент очереди истекает или вызывающая сторона отключается, остановите работу с новыми страницами, закройте активный контекст и освободите браузер согласно политике развёртывания. Фиксируйте, завершилась ли очистка. Тихая отмена, после которой процессы браузера продолжают работать, со временем проявится как нехватка памяти или необъяснимое повторное использование профилей.

Согласованность прокси и профиля

Рассматривайте назначение профиля и сетевой маршрут как одно проверенное решение. Язык и региональные параметры, часовой пояс и регион прокси должны описывать одну и ту же разрешённую среду. Выбор маршрута оставляйте в поддерживаемом сценарии браузера или развёртывания, а не распределяйте его между кодом страницы и несколькими внешними обработчиками.

При смене учётных данных сохраняйте профиль и набор страниц, пока проверяете новый маршрут. При смене пакета профиля сохраняйте утверждённый маршрут, пока проверяете новый пакет. Если менять оба сразу, сбой трудно классифицировать. После каждого изменения повторяйте обычные проверки приложения и записывайте только идентификаторы выпуска и результат, нужные поддержке.

Не записывайте учётные данные прокси в вывод консоли, трассировки, снимки экрана и метаданные заданий. Передавайте их через хранилище секретов развёртывания и ограничьте доступ служебными учётными записями, которые запускают разрешённый сценарий. Проверьте маскирование в журнале приложения, прежде чем включать tracing Playwright в продакшене.

Наблюдаемость без сбора страниц

Полезная телеметрия интеграции в основном операционная. Записывайте завершение запуска браузера, готовность первой страницы, длительность задачи, закрытие контекста, код завершения браузера, задержку в очереди и идентификаторы выпуска. Эти наблюдения показывают состояние системы без хранения содержимого страниц и подробной истории просмотров.

Снимки экрана, видео, трассировки и сетевые архивы могут содержать данные учётных записей или закрытое состояние приложения. Включайте их только для утверждённого обращения в поддержку или для сценария, который их уже требует. Установите контроль доступа и сроки хранения до начала сбора. Отключайте временную диагностику после решения проблемы.

Агрегируйте данные о ёмкости по группам развёртывания, а не привязывайте подробную активность браузера к отдельному сеансу. Динамики памяти, загрузки процессора, завершений браузера и выполненных заданий достаточно для большинства решений о масштабировании. Разделяйте проверку приватности и проверку производительности, если для их данных нужны разные сроки хранения.

Выпуск, откат и разбор проблем

Обновления и откат

Сначала выкатывайте новую версию браузера или Playwright на небольшую группу. Сравнивайте её с неизменённой группой при той же нагрузке, том же семействе профиля, той же политике маршрута и том же классе хоста. Остановитесь, если проверки приложения, стабильность браузера или результаты очистки расходятся с планом выпуска. Верните предыдущую пару версий, прежде чем проверять второе изменение.

Пакет отката должен включать прежний бинарный файл браузера, блокировку зависимостей автоматизации, совместимый пакет профиля и конфигурацию развёртывания. Проверяйте этот пакет, пока он актуален. Инструкция по откату бесполезна, если её бинарный файл удалён или пакет профиля просрочен.

После успешного выпуска удаляйте старые пакеты по политике хранения организации. Оставьте только запись о выпуске, нужную поддержке: пару версий, семейство профиля, группу развёртывания, период проверки и результат. Не храните полные трассировки только потому, что они были собраны в тестовом окружении.

Разбор проблем запуска и выполнения

Классифицируйте неудачное задание по первой видимой пользователю границе, которая не была пройдена. Сбой запуска, проверки профиля, первой навигации, проверки приложения и завершения относятся к разным владельцам. Сохраните обычный вывод терминала и код завершения, затем сравните назначенную единицу выпуска с последним успешным заданием.

Прежде чем менять сразу несколько параметров, вернитесь к последней рабочей паре версий. Подтвердите доступ к бинарному файлу, назначение профиля, доступность маршрута и ресурсы хоста обычными проверками развёртывания. Когда базовый результат восстановлен, вносите по одному изменению и повторяйте типовой сценарий приложения.

Не превращайте инцидент в продакшене в неограниченный осмотр страниц. Запись для поддержки должна содержать затронутую группу развёртывания, наблюдаемый результат, идентификаторы выпуска, корректирующее действие и итоговую проверку. Дополнительные сведения о страницах собирайте только с разрешения владельца приложения и если обычных операционных данных недостаточно.

Контрольный список для продакшена

• Используйте playwright-core, а не полный пакет playwright. Полный пакет скачивает собственный Chromium, который вам не нужен.
• Указывайте абсолютные пути для --bot-profile. Относительные пути могут разрешаться неверно в зависимости от рабочего каталога.
• Не задавайте viewport для контекстов браузера, если вам не нужно переопределить viewport профиля. Пусть размерами экрана управляет профиль.
• Задайте DISPLAY=:10.0 на серверах Linux, даже в режиме headless.
• Держите владение профилем явным. Используйте только назначение профиля, которое поддерживает выбранный сценарий BotBrowser, и применяйте его до первой страницы.
• Закрывайте браузеры по завершении. Незакрытая работа браузера продолжает занимать ресурсы хоста.
• Обрабатывайте ошибки запуска. Если запуск не удался, проверьте путь к бинарному файлу и право на его выполнение.

Частые вопросы

• Можно ли использовать полный пакет Playwright? Да, но он скачивает отдельный браузер, который для этой схемы не нужен. playwright-core отделяет библиотеку автоматизации от бинарного файла BotBrowser.
• Нужны ли скрипты страницы для настройки идентичности? Нет. Загрузите соответствующий пакет профиля при запуске браузера или примените поддерживаемый профиль для контекста до старта первой цели.
• Можно ли использовать Playwright codegen или инспектор? Используйте инструменты разработки Playwright с тем же собственным исполняемым файлом и той же конфигурацией профиля, что и в проекте. Держите версии профилей для разработки и продакшена согласованными.
• Как запустить на Ubuntu? Установите библиотеки времени выполнения, которые требует выбранный выпуск, и следуйте руководству по настройке headless-сервера. Графический путь выбирается по руководству по графическому бэкенду Linux.
• Можно ли использовать прокси для отдельного контекста? Да. Сценарии прокси Context и Live в BotBrowser требуют ENT Tier3. Применяйте прокси и профиль до старта первой страницы или воркера и не подменяйте этот маршрут аутентификацией на уровне фреймворка.
• Сколько воркеров можно запустить? Измерьте нагрузку на репрезентативных страницах целевого хоста. Используйте ограниченную очередь, оставляйте запас памяти и убедитесь в полном завершении перед увеличением параллелизма.
• Работают ли tracing и снимки экрана? Playwright предоставляет обе возможности, когда их поддерживают выбранная пара версий и рабочая среда. Подтвердите нужные приложению артефакты, установите контроль доступа и сроки хранения и учтите их расход ресурсов при оценке ёмкости.
• Можно ли использовать TypeScript? Да. playwright-core включает определения типов TypeScript.

Заключение

Используйте playwright-core, чтобы отделить автоматизацию от исполняемого файла BotBrowser, назначьте утверждённый профиль до первой страницы и рассматривайте маршрут, версию, очистку контекста и телеметрию как единый проверенный процесс. Так появляется повторяемая граница запуска без заявления о контроле над сторонним приложением.

Что BotBrowser покрывает в этом сценарии

BotBrowser поддерживает запуск через стандартный executablePath Playwright с --bot-profile и необязательным --proxy-server, поэтому выбранный профиль определяет идентичность браузера, а Playwright по-прежнему отвечает за навигацию, контексты и проверки в той же воспроизводимой конфигурации запуска. В этой схеме это означает одно проверенное определение запуска, которое команда может закрепить, повторить и откатить как единицу выпуска. BotBrowser не заменяет API автоматизации Playwright, не гарантирует никакого результата на стороннем сайте и не может контролировать тестируемое приложение, поставщика прокси или состояние учётной записи. Сценарии Per-Context и прокси Live дополнительно требуют ENT Tier3.

Установите playwright-core, укажите в executablePath бинарный файл BotBrowser и назначьте утверждённый профиль при запуске. Проверьте точную пару версий под предполагаемой нагрузкой до выпуска. Скачайте BotBrowser или изучите тарифы для нужного сценария.

По смежным темам смотрите Начало работы с Puppeteer об аналогичной схеме для Puppeteer, Рецепты CLI о других сочетаниях параметров, Управление профилями об организации профилей и Прокси на контекст о владении маршрутами для отдельных контекстов.

О четырёх поверхностях, которые должен покрыть первый запуск, читайте в карте начала работы.

Открытые источники

• BotBrowser на GitHub
• Руководство BotBrowser по Playwright
• API BrowserType в Playwright