Начало работы с автоматизацией браузера: карта

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

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

Кратко

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

Содержание

• Четыре поверхности начальной настройки
• Пройдите по кластеру начальной настройки
• Проведите первую сессию
• Спланируйте первый проект
• Сделайте запуск повторяемым
• Разберите первый сбой
• Практический итог

Четыре поверхности начальной настройки

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

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

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

Пройдите по кластеру начальной настройки

• Playwright с идентичностью профиля это путь запуска Playwright и его ловушки.
• Запуск Puppeteer и ловушки профиля охватывает аналог для Puppeteer.
• Интеграция профилей в Selenium охватывает владение сессией в Selenium.
• Профили браузера: форматы и ротация объясняет файл профиля, который вы передаёте.
• Руководство по лаунчеру охватывает профили, прокси и настройку.
• Рецепты CLI собирает конкретные примеры команд.
• Лёгкая автоматизация через протокол DevTools охватывает путь без фреймворка.
• Fixture и изоляция в автоматизации охватывает то, чем должен владеть первый запуск.
• Воспроизводимые отчёты об ошибках охватывает, что записывать при сбое первого запуска.
• Проверка отпечатка браузера охватывает ограниченную проверку того, что видит страница.

Хаб владеет порядком и формой записи. Каждая связанная статья владеет деталями своей поверхности и возможным сбоем.

Проведите первую сессию

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

{
  "runId": "first-run-20261019-01",
  "declared": {
    "driver": "[email protected]",
    "browserPackage": "standard-linux-x64",
    "profile": "fresh-temporary.enc",
    "mode": "headless"
  },
  "observed": {
    "install": "executable-started",
    "launch": "profile-loaded",
    "context": "closed-after-task",
    "evidence": "console-and-check-recorded"
  },
  "firstFailure": null,
  "testedOn": "2026-10-19"
}

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

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

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

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

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

Записывайте версии с обеих сторон. Версия драйвера и версия пакета браузера должны быть в той же записи, что и результат: общая настройка отказывает на другом слое, чем обновление драйвера. Когда следующий запуск ведёт себя иначе, две записи показывают, какая сторона сдвинулась.

Выбирайте безголовый режим осознанно. Безголовый первый запуск легче автоматизировать и проще вести в CI, а с интерфейсом легче отлаживать, когда страница рисуется не так, как ожидалось. Записывайте использованный режим: смена режима между запусками это другой эксперимент, и разница отрисовки в безголовом режиме не доказывает поведение с интерфейсом.

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

Спланируйте первый проект

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

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

Сделайте запуск функцией вида createSession({ profile, headless }), возвращающей объект сессии. Объект сессии владеет браузером, контекстом и методом закрытия. Задача получает сессию и не видит флагов запуска. Это соответствует тому, как Playwright и Puppeteer описывают владение контекстом, и означает, что задачу для одного драйвера можно адаптировать к другому без переписывания логики страницы.

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

Выбирайте драйвер под задачу, а не под демо

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

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

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

Решите, что должен доказать первый запуск

Первый запуск это проверка с одним вопросом, и вопрос должен быть записан до скрипта. «Запускается ли браузер с этим профилем» хороший первый вопрос. «Рисуется ли страница на объявленной платформе» хороший второй. «Принимает ли сайт сессию» это вопрос о сайте, и он приходит позже, в вашем собственном тесте.

Записывайте ожидаемый результат как значение, а не как ощущение. Например, ожидайте, что navigator.platform сообщит значение из профиля, или что собственная фикстура вернёт объект состояния фиксированной формы. Значение можно сравнивать между запусками, ощущение нельзя.

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

Сделайте запуск повторяемым

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

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

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

Держите профиль и очистку вместе

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

Для первого запуска предпочитайте свежий временный профиль (profileClass: "fresh-temporary"), и записывайте класс, а не путь, если профиль содержит что-то чувствительное. Свежий профиль изолирует первый запуск от прошлой активности и делает сравнение со вторым осмысленным. Долгоживущий профиль это законный следующий шаг, и он должен быть осознанным.

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

Автоматизируйте проверки, которые уже сделали вручную

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

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

Запускайте автоматизированный первый запуск (npm run first-run) перед слиянием любого изменения кода запуска. Код запуска мал и централен, изменение в нём затрагивает каждую задачу, поэтому самый дешёвый регрессионный тест это уже существующий.

Документируйте одну команду, которую команда реально наберёт

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

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

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

Разберите первый сбой

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

Исправляйте одну поверхность за запуск и сохраняйте запись. Первый запуск, завершающийся названной поверхностью, готов стать шаблоном для остального проекта.

Практический итог

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

Источники

• Playwright: контексты браузера
• Puppeteer: управление браузером
• MDN: WebDriver
• Документация BotBrowser: начало работы
• Документация BotBrowser: управление профилями