Подробный обзор playwright-cli: команды, сценарии, отличия от Playwright Test и реальные ограничения

С Playwright сейчас легко запутаться уже на уровне названий. Под рукой есть привычный CLI внутри самого Playwright Test с командами вроде npx playwright test, codegen и show-report. И есть отдельный агентный пакет @playwright/cli с командой playwright-cli, который Microsoft продвигает как интерфейс для браузерной автоматизации из командной строки и для работы с coding agents. Именно вокруг этой новой сущности чаще всего и возникает путаница.

Если говорить по делу, playwright-cli нужен не для того, чтобы заменить весь Playwright, а чтобы быстро управлять браузером без написания полноценного тестового проекта. Открыть страницу, получить снимок структуры, кликнуть по элементу, сохранить состояние, посмотреть сеть, выполнить кусок кода, записать trace, снять скриншот, переключить вкладку или поднять визуальную панель наблюдения за сессиями. Для разовой проверки, живой отладки и агентных сценариев инструмент очень удобен. Для серьезного набора регрессионных тестов - уже не всегда.

Что такое playwright-cli в 2026 году

По документации Playwright, playwright-cli - отдельный CLI для автоматизации браузера, рассчитанный прежде всего на coding agents. Microsoft прямо описывает подход как более экономный по контексту, чем MCP, потому что команды остаются короткими и не тянут за собой тяжелые схемы инструментов и длинные деревья доступности страницы.

Устанавливается пакет отдельно:

npm install -g @playwright/cli@latest
 playwright-cli --help

Минимальное требование - Node.js 18 или новее. Можно ставить глобально, можно запускать локально через npx playwright-cli. Для агентов предусмотрена отдельная установка skills через playwright-cli install --skills.

Главная развилка: playwright-cli, Playwright Test CLI и MCP

Дальше важно не смешивать три соседних инструмента.

Практический вывод простой. Нужны тесты с ретраями, матчерами, фикстурами, HTML-репортами и CI - берите Playwright Test. Нужен инструмент, который из shell быстро двигает браузер и живет как утилита - берите playwright-cli. Нужен более «разговорчивый» мост для агентной логики - смотрите в сторону MCP.

Как устроена работа playwright-cli на самом деле

Логика у инструмента простая, но интересная. Вы открываете браузерную сессию, дальше выполняете короткие команды, а после каждой команды CLI может вернуть текущее состояние страницы. В примерах из официального руководства после действия выводятся URL, заголовок страницы и snapshot, который сохраняется в локальную служебную директорию. Внутри snapshot у элементов появляются референсы вида e15, e21 и так далее. Дальше на эти референсы можно ссылаться прямо в командах.

По сути получается промежуточная модель между «написать код» и «тыкать мышкой». Инструмент сначала показывает карту страницы, потом позволяет обращаться к узлам по коротким идентификаторам. Такой режим хорош в двух случаях. Первый - когда человек вручную прогоняет сценарий и не хочет писать boilerplate. Второй - когда агенту нужно дать компактный и предсказуемый интерфейс.

Базовый сценарий работы: от открытия страницы до снимка результата

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
 playwright-cli type "Buy groceries"
 playwright-cli press Enter
 playwright-cli snapshot
 playwright-cli check e21
 playwright-cli screenshot

С технической точки зрения здесь важно несколько вещей. Команда open поднимает браузер и может сразу перейти по URL. Команда type печатает в активный редактируемый элемент, а не в произвольный узел страницы. Команда snapshot дает актуальное состояние DOM в удобном для CLI-потока виде. Команда check работает по element ref. Команда screenshot может снять либо всю страницу, либо отдельный элемент.

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

Какие команды действительно важны

У playwright-cli уже довольно широкий набор команд, и сильная сторона как раз в том, что покрытие вышло далеко за пределы «открыть страницу и нажать кнопку».

Управление страницей и элементами

Ключевой набор выглядит так: open, goto, click, type, fill, select, check, uncheck, hover, drag, upload, close. Уже здесь видно, что CLI закрывает почти весь типовой пользовательский путь без куска собственного кода.

Элементы можно адресовать тремя способами. Первый - через refs из snapshot. Второй - через CSS. Третий - через role-селекторы Playwright, например role=button[name=Submit]. В практической работе refs почти всегда оказываются самым удобным вариантом, потому что уменьшают шум в командах. Но при динамическом DOM refs быстро устаревают, и тогда приходится снова обновлять snapshot.

Снимки, скриншоты и PDF

Команды snapshot, screenshot и pdf превращают CLI в удобный инструмент для документирования проблемы. Если инженер хочет быстро показать состояние страницы, не обязательно собирать полноценный trace. Иногда хватает snapshot плюс скриншот. Snapshot полезен тем, что содержит структурное состояние, а не только картинку.

Навигация, клавиатура и мышь

go-back, go-forward, reload, press, keydown, keyup, mousemove, mousedown, mouseup, mousewheel. Здесь уже видно, что CLI старается покрыть не только «форму и кнопку», но и более тонкие сценарии, включая горячие клавиши и нестандартные последовательности действий.

Работа с вкладками

Есть команды tab-list, tab-new, tab-select, tab-close. Для многостраничных потоков, авторизации через отдельное окно или проверки редиректов набор вполне рабочий. Но для длинных сценариев с большим количеством вкладок CLI начинает проигрывать обычному коду, потому что управление быстро становится трудно читаемым.

Сеть и перехват запросов

Наличие network, route, route-list и unroute - одна из самых сильных сторон инструмента. Можно посмотреть запросы после загрузки страницы и замокать сеть без написания тестовой обвязки. Для воспроизведения багов фронтенда, проверки поведения при ошибке API или локальной имитации бэкенда набор очень полезный.

Но здесь же возникает и первое серьезное ограничение. Как только логика моков становится сложной, shell-команды начинают проигрывать нормальному TypeScript-коду с функциями, условиями и повторным использованием кусочков логики.

Cookies, localStorage и storage state

Команды state-save и state-load позволяют сохранять и загружать storage state. Плюс есть отдельные операции для cookies и localStorage: список, чтение, запись, удаление, очистка. Для задач с авторизацией, A/B-флагами, экспериментами и восстановлением сеанса такой набор особенно ценен.

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

DevTools-подобные команды

В наборе есть console, eval, run-code, tracing-start, tracing-stop, video-start, video-chapter, video-stop. Тут уже видно, что CLI пытается стать не просто пультом управления браузером, а тонким диагностическим слоем.

eval и run-code особенно полезны для быстрых проверок гипотез. Нужно проверить значение в DOM, дернуть функцию страницы, посмотреть runtime-состояние, снять кусок данных из window или быстро выполнить Playwright-фрагмент без создания проекта - можно сделать прямо из консоли.

Сессии: одна из лучших идей в playwright-cli

Самая практичная часть нового CLI - сессии. По умолчанию профиль браузера живет в памяти, значит cookies и storage сохраняются между вызовами внутри сессии, но исчезают после закрытия браузера. Если нужен более долговечный режим, можно использовать --persistent.

Есть и именованные сессии. Например, можно держать одну сессию под рабочий проект, вторую под тестовую площадку, третью под админку. Команды list, close-all, kill-all, delete-data помогают управлять жизненным циклом. Для агентной автоматизации это сильный ход, потому что сессия становится почти отдельным рабочим пространством.

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

Команда show и визуальный мониторинг

Отдельного внимания заслуживает playwright-cli show. Инструмент открывает панель наблюдения за активными сессиями с живыми превью, текущими URL и заголовками страниц. Для человека такой режим полезен как диспетчер. Для команды - как быстрый способ понять, что сейчас происходит в браузерах, которые крутит агент или автоматизация.

Хорошая новость в том, что панель превращает CLI в нечто среднее между headless-автоматизацией и удаленным ручным управлением. Плохая новость в том, что при масштабировании на много сессий удобство быстро упирается в визуальный шум.

Headless по умолчанию, но headed нужен чаще, чем кажется

CLI работает headless по умолчанию. Формально логично - меньше шумит и лучше подходит для автоматизации. На практике headed-режим через --headed нужен довольно часто, особенно в начале сценария, когда вы только ловите правильные селекторы или пытаетесь понять, почему UI ведет себя странно.

Еще одна тонкость касается выбора браузера. В новом CLI можно открыть не только Chromium-подобный движок, но и явно попросить chrome, firefox, webkit или msedge. Для проверки различий движков полезно, хотя в сложных матрицах кроссбраузерного тестирования классический Playwright Test все равно удобнее.

Конфигурация и подключение к существующему браузеру

playwright-cli умеет читать конфиг через --config и автоматически подхватывает файл .playwright/cli.config.json, если он есть в проекте. По описанию Playwright, через конфиг можно задавать browser options, context options, сетевые правила, таймауты и другие параметры. Для командной утилиты наличие такого слоя настройки очень важно. Без него CLI быстро превратился бы в набор «одноразовых» команд.

Есть и еще одна интересная возможность - подключение к уже открытому браузеру через open --extension. Но здесь нужен Playwright MCP Bridge browser extension. Для отладки пользовательской среды ход полезный. Для безопасной корпоративной эксплуатации - повод внимательно посмотреть, где именно и с какими правами такая схема будет использоваться.

Где playwright-cli реально хорош

Лучше всего инструмент раскрывается не в лабораторных примерах, а в практических задачах.

• Быстрая ручная проверка UI без создания тестового файла
• Пошаговая агентная автоматизация внутри IDE или coding assistant
• Отладка багов фронтенда с просмотром сети, console и storage
• Авторизационные сценарии с повторным использованием сохраненного состояния
• Быстрое снятие артефактов: screenshot, snapshot, PDF, video, trace
• Работа с несколькими сессиями и стендами параллельно

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

Где playwright-cli начинает мешать

У инструмента есть четкая граница полезности. Как только сценарий становится длинным, ветвистым и повторяемым, shell-команды теряют прозрачность. Условные переходы, циклы, параметризация, повторное использование шагов, читаемая структура ошибок, нормальные assertions, retry-логика, проекты и репортеры - весь этот мир гораздо лучше чувствует себя в @playwright/test.

Есть и другая проблема. Команды выглядят простыми, но простота иногда обманчива. Например, работа через refs из snapshot удобна только до тех пор, пока DOM не обновился и ссылка на элемент не устарела. Динамические интерфейсы быстро показывают предел такого подхода.

Третья граница - поддерживаемость. Если команда или агент регулярно прогоняет один и тот же бизнес-критичный сценарий, лучше потратить время и оформить логику в тестовый код. Иначе через пару недель никто уже не поймет, почему именно такая последовательность shell-вызовов считается «истиной».

А как насчет обычного CLI внутри Playwright Test

Тут тоже нужен отдельный разговор, потому что многие ищут «обзор playwright-cli», а на деле имеют в виду привычный npx playwright. По справке Playwright Test CLI по-прежнему остается главным интерфейсом для тестов. Через него запускаются test, codegen, show-report, show-trace, install, install-deps, merge-reports, clear-cache и другие команды.

Именно этот CLI дает зрелую тестовую экосистему: раннер, параллельность, режим --ui, headed-запуск, выбор проектов, blob-репорты, HTML-отчеты, trace viewer. Поэтому честный совет такой: не пытайтесь выбирать «или новый playwright-cli, или старый npx playwright». Инструменты решают разные задачи и отлично могут жить рядом.

Codegen и новый playwright-cli - не одно и то же

Еще одно частое заблуждение - считать, что новый playwright-cli просто заменил npx playwright codegen. Нет. Codegen остается частью Playwright Test CLI и по-прежнему хорош для записи действий и генерации кода на разных языках. Playwright в документации отдельно пишет, что codegen старается подбирать устойчивые локаторы и умеет генерировать действия и assertions.

Но codegen создает код, а новый playwright-cli строит интерактивный командный контур вокруг живой браузерной сессии. По ощущениям это разные философии работы. Первая про «запиши и перенеси в проект». Вторая про «делай атомарные шаги прямо сейчас».

Пример здравого рабочего процесса

Самый разумный путь обычно выглядит так. Сначала инженер или агент использует playwright-cli, чтобы быстро понять сценарий, проверить спорные места, сохранить state, посмотреть сеть, нащупать нужные селекторы и собрать скриншоты. Потом стабильный и ценный сценарий переносится в обычный Playwright-тест. После этого включаются нормальные assertions, репортеры, trace и CI.

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

Что с производительностью и надежностью

Сам по себе CLI не делает браузер дешевым. Если сценарий тяжелый, страница насыщена JavaScript, а параллельно работает несколько headed-сессий, нагрузка по CPU и памяти никуда не денется. Кроме того, устойчивость автоматизации все равно зависит от качества локаторов, таймингов загрузки, нестабильных third-party-виджетов и сетевых флапов.

Новый CLI не отменяет фундаментальные проблемы UI-автоматизации. Он просто делает первые шаги и диагностику быстрее.

Можно ли использовать playwright-cli для скрейпинга

Технически можно, потому что под рукой есть полноценный браузер, сеть, storage и выполнение кода на странице. Практически нужно быть осторожнее. Для массового сбора данных браузерный путь дороже по ресурсам, медленнее и заметнее, чем работа через API или обычные HTTP-клиенты. На сайтах с антибот-защитой ситуация осложняется еще сильнее.

Если задача касается сбора данных, авторизации, ограниченных разделов сайта или обхода технических барьеров, работайте только в рамках закона, правил площадки и внутренних требований компании. Не используйте playwright-cli для обхода блокировок, капч, антибот-защиты и других защитных механизмов.

Кому стоит брать playwright-cli, а кому лучше пройти мимо

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

Лучше не делать ставку только на playwright-cli командам, которым нужен воспроизводимый regression suite, строгая CI-дисциплина, понятные отчеты по качеству и долговременная поддержка сотен сценариев. В таком случае CLI остается хорошим разведчиком, но не главным рабочим инструментом.

Итог: где у инструмента реальная ценность

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

Но называть playwright-cli заменой Playwright Test было бы ошибкой. Скорее речь идет о хорошем «оперативном» инструменте. Он помогает исследовать, отлаживать и быстро воспроизводить сценарии. А когда сценарий доказал свою ценность, правильнее перенести логику в обычные тесты и уже там строить долгоживущую автоматизацию.

Если нужен один короткий вывод, он такой: playwright-cli хорош как быстрый браузерный скальпель, а не как полный хирургический набор.