Playwright MCP: как настроить и получить первые автотесты
Коротко
Установка — одна команда: claude mcp add playwright -- npx @playwright/mcp@latest. Двойное тире обязательно: оно отделяет флаги самого Claude Code от команды запуска сервера, и большинство туториалов его теряют. Проверка — claude mcp list, там должно быть ✔ Connected, или /mcp внутри сессии со списком инструментов.
Дальше важное различие, из-за которого чаще всего и не получается. Playwright MCP даёт агенту руки: он открывает браузер, кликает, читает страницу как дерево доступности, видит ошибки в консоли и сетевые запросы. Но сам по себе он не создаёт тестов — сессия закончилась, и ничего не осталось. Автотесты — это отдельный пакет @playwright/test и файлы *.spec.ts в репозитории. Рабочая схема такая: агент через MCP проходит сценарий руками, выясняет реальные селекторы и тайминги, а потом пишет по итогам обычный тест-файл, который вы запускаете через npx playwright test и в CI без всякого MCP.
Вечера хватает на 5–10 тестов по критичным сценариям: логин, форма, оформление заказа.
В чём задача
Типичная ситуация: сайт живёт, правки катятся, и раз в месяц отваливается что-то незаметное — форма перестаёт отправляться, кнопка оплаты уводит в 500, письмо не уходит. Узнаёте вы об этом от пользователя через неделю.
Ручной QA на это нанимать дорого, а писать тесты самому долго: половина времени уходит не на логику, а на выяснение, каким селектором ткнуть в кнопку и сколько ждать редиректа. Вот эту половину и снимает MCP — агент выясняет её эмпирически, открыв ваш реальный сайт.
| Playwright MCP | @playwright/test |
|
|---|---|---|
| Что это | MCP-сервер, инструменты для агента | Тест-раннер и библиотека |
| Когда работает | Только внутри сессии с агентом | Всегда: локально, в CI, по крону |
| Что остаётся после | Ничего (если не сохранить) | Файлы *.spec.ts в git |
| Зачем нужен | Разведка, отладка, поиск селекторов | Регрессия |
| Токены | Тратит, и много | Не тратит |
Нужны оба. MCP без тест-раннера — это красивая демонстрация; тест-раннер без MCP — это вы, вручную выясняющий селекторы.
Пошагово
1. Проверьте Node. Нужен Node.js 18 или новее — это требование репозитория playwright-mcp. На Node 16 сервер молча не поднимется.
node -v
2. Подключите MCP-сервер. Синтаксис claude mcp add [опции] <имя> -- <команда> описан в документации Claude Code:
claude mcp add -s project playwright -- npx @playwright/mcp@latest --browser chromium
Флаг -s project пишет конфиг в .mcp.json в корне проекта — файл коммитится, и у всей команды одинаковое поведение. Без флага сервер попадёт в локальный скоуп и будет только у вас. Общая механика подключения любых серверов разобрана в отдельном материале про то, как подключить MCP к Claude Code.
3. Поставьте браузеры и тест-раннер:
npm i -D @playwright/test
npx playwright install --with-deps chromium
--with-deps на Linux доставит системные библиотеки; без него получите «Missing system dependencies» при первом же запуске.
4. Проверьте связь. claude mcp list — статус должен быть ✔ Connected. Затем внутри сессии /mcp: у playwright видно пару десятков инструментов (навигация, клик, ввод, снапшот, вкладки, сеть, консоль).
5. Прогоните сценарий руками агента. Не просите сразу «напиши тесты». Сначала разведка:
Открой https://мойсайт.ру, пройди сценарий: клик «Оставить заявку»,
заполни форму валидными данными, отправь. После каждого шага делай
снапшот и покажи, какие ушли сетевые запросы и что в консоли.
В конце выпиши список ролей и доступных имён элементов, которые
использовал для поиска.
Последнее предложение — самое ценное. Вы получите готовый список локаторов вида getByRole('button', { name: 'Отправить' }), проверенных на живой странице.
6. Попросите оформить тест. Теперь, когда сценарий пройден:
Оформи пройденный сценарий как tests/lead-form.spec.ts на @playwright/test.
Используй только те локаторы, что реально сработали. Проверь: успешный
сабмит, пустое обязательное поле, невалидный email. Никаких
waitForTimeout — только web-first assertions.
Запрет на waitForTimeout стоит вписывать явно: агенты по умолчанию любят «подождать три секунды», и именно с этого начинается флакающий тест.
7. Запустите без агента:
npx playwright test
npx playwright show-report
Проверка результата
Тест считается рабочим не когда он зелёный, а когда он умеет краснеть. Сломайте вручную то, что он проверяет: закомментируйте обработчик отправки формы, поменяйте текст кнопки, верните 500 с эндпоинта. Прогон должен упасть. Если он остался зелёным — тест ничего не проверяет, такое бывает часто: агент дописал expect(page).toBeTruthy() и ушёл.
Второй чек — прогон три раза подряд. Плавающий результат означает гонку по таймингам, а не «иногда бывает».
Третий — логин. Если сценарий за авторизацией, не гоняйте форму входа в каждом тесте: сохраните состояние один раз через storageState и переиспользуйте. Пример из документации Playwright по авторизации:
// tests/auth.setup.ts
setup('authenticate', async ({ page }) => {
await page.goto('/login');
await page.getByLabel('Email').fill(process.env.TEST_EMAIL!);
await page.getByLabel('Пароль').fill(process.env.TEST_PASSWORD!);
await page.getByRole('button', { name: 'Войти' }).click();
await page.waitForURL('/dashboard');
await page.context().storageState({ path: 'playwright/.auth/user.json' });
});
Файл состояния протухает вместе с сессией — в документации это оговорено прямо: истёкшее состояние надо удалять и логиниться заново. Держите playwright/.auth/ в .gitignore: там живые куки.
Дальше это уезжает в CI по официальной инструкции — и вот тут MCP уже не участвует вообще. Готовый набор промптов на генерацию тестов лежит в карточке write-tests, а роль для агента — в QA Automation / SDET.
Подводные камни
| Симптом | Причина | Что делать |
|---|---|---|
Сервер не появляется в /mcp |
Потеряно -- перед npx |
claude mcp add playwright -- npx @playwright/mcp@latest |
✘ Failed to connect |
Node ниже 18, опечатка в .mcp.json |
node -v, запустить claude --debug |
| «Missing system dependencies» | Не поставлены библиотеки браузера | npx playwright install --with-deps |
| Браузеры не качаются | Корпоративный прокси или блокировка | Задать HTTPS_PROXY, либо зеркало через PLAYWRIGHT_DOWNLOAD_HOST |
| Агент делает снапшот за снапшотом | Нет явной инструкции | «Снапшот один раз, дальше ищи по роли и действуй» |
| Лимит контекста кончается за 10 минут | Снапшоты страниц огромные | Дробить задачу, гонять на одной странице за сессию |
| Тест зелёный на пустом сайте | Нет содержательных assert'ов | Ломать руками и смотреть, падает ли |
| Прогон в CI падает, локально нет | Headed против headless, шрифты, таймзона | Прогнать локально --headed=false, зафиксировать locale |
Отдельно про честные ограничения, которых в англоязычных гайдах обычно нет.
MCP дорогой по токенам. Каждый снапшот страницы — это дерево доступности целиком, на насыщенном интерфейсе легко тысячи токенов. Разведка сценария оплаты может съесть заметную часть окна контекста за один заход. Поэтому финальные тесты и гоняются раннером, а не агентом.
Оплату по-настоящему не протестируешь. Боевой эквайринг в тестах трогать нельзя. Нужна тестовая среда платёжного провайдера с тестовыми картами, и у российских провайдеров она обычно включается по заявке и отдельным ключом. Без неё максимум, что проверяется, — что кнопка ведёт на страницу оплаты и приходит корректный редирект.
Персональные данные. Если тест логинится реальным аккаунтом или заполняет форму настоящими данными, вы прогоняете персональные данные через сторонний сервис. Заводите отдельные тестовые учётки с синтетическими данными — это и требование гигиены по 152-ФЗ, и просто здравый смысл.
Не заменяет QA. Агент проверит то, что вы описали. Он не заметит, что кнопка уехала за экран на iPhone SE, если вы не попросили. Визуальную регрессию закрывают снапшот-тесты, а продуктовые сценарии всё равно придумывает человек.
Карточка сервера с параметрами запуска и списком инструментов — Playwright MCP в арсенале.
Частые вопросы
Playwright MCP не работает — с чего начать?
С трёх проверок по порядку. Первая: claude mcp list — если сервера нет в списке вообще, дело в команде добавления, чаще всего в потерянном --. Вторая: если статус ✘ Failed to connect, запустите claude --debug и посмотрите, что пишет процесс при старте — обычно там либо старый Node, либо битый JSON в .mcp.json. Третья: если сервер подключился, а браузер не открывается, значит не выполнен npx playwright install. Эти три случая закрывают почти все обращения.
Нужен ли @playwright/test, если есть MCP?
Нужен, если вам нужны именно автотесты. MCP живёт внутри сессии с агентом: закрыли — ничего не осталось, в CI он не запустится и по расписанию тоже. Раннер @playwright/test — это то, что реально ловит регрессию каждый деплой. MCP окупается на этапе написания и отладки, а не эксплуатации.
Можно ли натравить это на прод?
На чтение — да, на изменение данных — нет. Тест, который каждый час создаёт заявку в боевой CRM, быстро станет вашей главной проблемой. Минимум: отдельный стенд или тестовый режим с пометкой источника, чтобы такие заявки отфильтровывались. Если стенда нет, ограничьтесь сценариями без сабмита: доступность страниц, отсутствие 500, наличие ключевых элементов.
Сколько времени занимает первый набор?
По моему опыту, вечер — это 5–10 тестов на связном сайте, где есть человеческая вёрстка. Если разметка сгенерирована и кнопки без текста и aria-label, агент не найдёт стабильных локаторов, и вы потратите время на расстановку data-testid. Это, кстати, лучшее вложение перед началом: пять атрибутов в вёрстке экономят час подбора селекторов.
Работает ли это с другими агентами, не Claude Code?
Да, @playwright/mcp — обычный MCP-сервер и подключается к любому клиенту, поддерживающему протокол: VS Code, Cursor, Windsurf, Claude Desktop. Различается только место конфига: в Claude Code это .mcp.json или ~/.claude.json, у остальных свои пути. Сам блок mcpServers с command: npx и args: ["@playwright/mcp@latest"] везде одинаковый.