Страница с игрой уже написана и открывается в браузере: доска рисуется, фигуры двигаются, кнопка "Новая партия" на месте. Вот только сам агент эту страницу ни разу не видел. Он работал с текстом файлов, а браузер запускали вы, смотрели вы, и рассказывали ему, что получилось, тоже вы. Playwright закрывает ровно этот разрыв: агент открывает ту же страницу, находит на ней нужный элемент, нажимает и читает, что после этого изменилось.
Ниже разберём этот цикл по шагам на примере шахматной страницы: открыть, посмотреть, выбрать элемент, подействовать, прочитать новое состояние. Установку и подключение сервера здесь не повторяем - если Playwright у вас ещё не подключён, инструкция лежит в README проекта.
Откройте нужную страницу
Что доказывает надпись Connected?
Ровно одно: Claude Code договорился с сервером Playwright и получил от него список инструментов. Ни одной страницы при этом ещё не открыто, браузер, вполне возможно, даже не запущен. Connected - это про соединение, а не про то, что ваша игра работает и агент её видит.
Посмотреть текущий статус можно командой /mcp: она перечислит подключённые серверы и то, что каждый из них умеет. Дальше начинается настоящая работа, и первое, что для неё нужно, - адрес страницы.
Локальная игра живёт либо файлом на диске, либо на локальном сервере, и порт у такого сервера не один и тот же на все случаи жизни. 5173, 8000, 3000 - зависит от того, чем вы её запустили. Адрес берите оттуда, где он реально напечатан: из вывода команды запуска или из адресной строки браузера, в котором вы игру только что смотрели. Угаданный порт даёт либо пустую страницу, либо вообще чужой проект, и по ответу инструмента это не всегда очевидно.
Само открытие - отдельный вызов, browser_navigate, у него один параметр: url. Поручение агенту при этом звучит обычным языком:
Открой http://localhost:5173/ через Playwright
и покажи заголовок страницы, которая открылась.После открытия сверьте две вещи: адрес, на который агент реально сходил, и название страницы. Это занимает секунду, а экономит целую серию действий, выполненных не там. Особенно если у вас параллельно крутится ещё пара локальных проектов, и один из них тоже отвечает на localhost.
Playwright запускает браузер под себя. Ваши вкладки, расширения и уже выполненные входы в аккаунты туда не переезжают: по умолчанию это отдельный профиль, обособленный от вашего обычного браузера. Для локальной игры это ничего не меняет, а вот ожидание "он же откроет сайт, где я залогинен" оправдается не само собой.
Что агент видит на странице
Посмотреть на открытую страницу можно тремя разными способами, и дают они принципиально разное:
| Что хотим | Инструмент | Что приходит в ответ |
|---|---|---|
| Увидеть, как выглядит | browser_take_screenshot | изображение страницы |
| Узнать, из чего состоит | browser_snapshot | текстовое дерево элементов: роли, названия, ссылки на элементы |
| Прочитать конкретное значение | browser_evaluate | результат небольшого выражения, посчитанного прямо на странице |
Все три ветки начинаются с одной страницы, но возвращают разные данные. Снимок помогает найти кнопку, а значение data-turn нужно прочитать отдельно. Изображение доски само по себе не раскрывает её HTML-атрибуты.
Скриншот - это картинка. Он отлично отвечает на вопросы "как это выглядит" и "что где расположено", но сам не даёт ссылки на элемент для browser_click. В основном режиме Playwright MCP для действий используют снимок доступности. Клики по координатам доступны отдельно, если включены соответствующие инструменты.
Снимок доступности - это как раз описание элементов. Не картинка, а текст: список того, из чего собрана страница, с ролями (кнопка, ссылка, поле ввода), названиями и ссылками, по которым к элементу можно потом обратиться. Именно на него агент и опирается, когда куда-то жмёт. Схематично одна кнопка выглядит там примерно так:
- button "Новая партия" [ref=e12]
- button "Отменить ход" [ref=e13]Это набросок для понимания формы, а не настоящий вывод инструмента: точный формат зависит от версии сервера, и запускать его ради статьи мы не станем. Важна здесь не пунктуация, а сам факт - кнопка приходит агенту как строка с ролью, названием и ссылкой, а не как прямоугольник с текстом.
А теперь то место, на котором чаще всего спотыкаются. Метка data-turn, по которой в нашей игре видно, чей сейчас ход, в снимок доступности не попадает: он строится из ролей, названий, состояний и ссылок на элементы, а не из разметки страницы. Произвольный data-атрибут в этот список не входит. Значение метки при этом может мелькнуть в снимке отдельно - если страница ещё и печатает его видимым текстом; но это уже текст на странице, а не прочитанный атрибут, и путать одно с другим не стоит.
Такие значения читают отдельной операцией, инструментом browser_evaluate. Он выполняет короткое выражение в контексте страницы и возвращает результат - это уже запуск кода на странице, а не просто чтение, поэтому агент иногда спросит разрешение, прежде чем это сделать. Выражение агент составит сам, но выглядит оно примерно так:
// найти элемент с меткой хода и вернуть её значение
() => document.querySelector('[data-turn]')?.getAttribute('data-turn') ?? nullСнимок доступности - это выжимка, а не полная копия разметки страницы. В нём есть то, по чему можно опознать и нажать элемент, но нет всего подряд. Поэтому "агент сделал снимок" и "агент прочитал все атрибуты" - разные утверждения, и второе из первого не следует.
Как агент выбирает элемент
Почему клик по координатам однажды промахивается мимо кнопки?
Потому что координаты описывают не кнопку, а точку на экране. Растянули окно, свернули боковую панель, поменяли масштаб шрифта, у страницы добавилась одна строка сверху - и точка осталась там же, а кнопка уехала. Клик при этом честно выполнится: просто по пустому месту.
Поэтому основной способ выбора другой. У инструмента browser_click два поля, которые здесь важны: element - человекопонятное описание вида "кнопка Новая партия", по которому вы понимаете, куда агент собрался нажать, и target - ссылку на элемент из снимка или уникальный селектор. Здесь разберём выбор по ссылке из снимка. Ссылка привязана к тому снимку, из которого её взяли, и попадает клик именно по ней. Ввод текста устроен так же, только инструмент называется browser_type и к описанию элемента добавляется сам текст.
Устойчиво здесь не сама ссылка, а способ её найти. Роль плюс название - пара довольно постоянная: кнопка "Новая партия" остаётся кнопкой "Новая партия" и после того, как дизайнер подвинул её на другой край экрана. По этой паре агент в любом новом снимке заново находит нужный элемент и берёт из него свежую ссылку - именно поэтому дальше в статье и повторяется правило "после действия смотрите заново".
С клеткой доски сложнее: клеток 64, и все они одинаковые по роли. Тут выручает метка от самого приложения. Если у клетки есть собственное имя, e2 или e4, попасть в неё можно точно; если все клетки в снимке безымянные, выбрать нужную только по роли и названию не получится. Тогда нужно проверить, есть ли у клетки другой однозначный признак в разметке, или использовать доступные координатные инструменты.
Координатные инструменты в Playwright MCP тоже есть, но в обычной сборке они выключены и включаются отдельно - на случай, когда элемент иначе не достать, например на canvas. Раз в обычной сборке их нет, действовать по одной картинке и правда нечем: ровно об этом было предупреждение про скриншот в начале раздела.
Действие и новое состояние
Стрелка слева замыкает цикл: перед следующим действием агент использует актуальное описание страницы. Если ответ на предыдущее действие уже содержит свежий снимок, можно опираться на него. Сам факт выполненного клика ещё не подтверждает нужное изменение.
Соберём всё в один маршрут, который можно поручить целиком. Пять шагов, и после каждого понятно, что должно стать видно. Маршрут рассчитан на то, что клетки у нашей доски подписаны - те самые e2 и e4 из предыдущей секции; без подписей для шага 4 понадобится другой способ однозначно выбрать клетки.
| Шаг | Что делает агент | Что становится видно |
|---|---|---|
| 1 | открывает адрес игры | заголовок страницы, доска на месте |
| 2 | нажимает кнопку "Новая партия" | фигуры в стартовой расстановке |
| 3 | читает data-turn | white |
| 4 | делает ход e2-e4 через интерфейс страницы | пешка сдвинулась на две клетки |
| 5 | читает data-turn и то, что стоит на e4 | black, на e4 белая пешка |
Слева показано исходное состояние, справа ожидаемый результат хода. Нижний блок связывает их проверкой: агент заново читает метку хода и положение фигур, затем сравнивает значения. Для более полной проверки перемещения стоит также убедиться, что исходная клетка e2 освободилась. Одна смена white на black ещё не подтверждает, что пешка оказалась именно на e4.
Про data-turn стоит сказать прямо: это договорённость конкретного приложения. Автор страницы решил выставлять такую метку, и поэтому её можно прочитать. Playwright её не создаёт и ниоткуда не берёт, он умеет только достать то, что на странице уже есть. На чужой странице, где такой метки не завели, этот приём не сработает, и придётся опираться на то, что видно глазами.
И главное правило после любого действия: состояние читают заново. Снимок, сделанный до клика, описывает страницу до клика, каким бы свежим он ни казался. Ссылки на элементы из него после перерисовки доски могут уже никуда не вести, а отдельно прочитанное до клика значение data-turn тоже уже могло измениться. Подействовали - смотрите снова.
Если приложение не отдало нужное значение, правильный ответ агента - "прочитать не получилось, такого атрибута на странице нет". Правдоподобное black, выведенное из того, что ход вроде бы сделан, выглядит точно так же, как настоящее прочитанное значение, но доказывает ровно ничего. Просите показывать сами прочитанные значения, а не пересказ.
Когда действие не получилось
Самая частая осечка звучит как "элемент не найден". Разбирается она по короткой цепочке:
- проверьте, что открыта та страница. Адрес и заголовок - те же две вещи, что и в самом начале;
- убедитесь, что страница готова. Игра могла ещё не догрузиться, а кнопка появиться на секунду позже запроса;
- возьмите свежий снимок. Не тот, что уже лежит в разговоре, а новый;
- выберите элемент заново, по актуальному описанию из этого снимка, и повторите действие.
Одна из возможных причин обнаружится на третьем шаге: элемент всё ещё на странице, но ссылка на него устарела.
Скриншот в разборе тоже пригодится, но не как универсальное средство. Он отвечает на вопрос "как страница выглядит и что где расположено" - например, показывает, что доска отрисовалась пустой или что поверх неё висит модальное окно. Если очередь хода показана текстом на странице, её можно увидеть и на скриншоте. Но точное значение атрибута data-turn подтверждает только его чтение. Два разных вопроса, два разных инструмента; путать их - значит смотреть на картинку и спорить о данных.
Как это меняет манеру работы
Поручение агенту перестаёт быть списком кликов и становится маршрутом с точками проверки. Вот то же самое, что мы разобрали, одним текстом:
Открой http://localhost:5173/ через Playwright.
1) нажми "Новая партия";
2) прочитай data-turn и покажи значение;
3) сделай ход e2-e4 через интерфейс страницы;
4) прочитай data-turn и то, что стоит на e4, ещё раз.
Если какого-то из этих значений на странице нет, скажи об этом
и не подставляй его сам.Что тут стоит держать в голове:
- адрес всегда настоящий, взятый из вывода запуска, а не примерный;
- в поручении есть строки "прочитай и покажи" - без них у вас останется только рассказ о результате;
- состояния показываются парой, до и после действия. Одно значение в конце ничего не доказывает, потому что неизвестно, каким оно было в начале;
- снимок, скриншот и чтение атрибута отвечают на разные вопросы, и выбирать их стоит по вопросу, а не по привычке;
- одного учебного маршрута достаточно. Пройденный ход e2-e4 не означает, что вся партия дальше пойдёт по правилам: это отдельная и куда более серьёзная проверка.
Проще всего запомнить так: браузер даёт агенту руки и глаза, но не даёт готовых выводов. Открыть страницу, нажать и прочитать значение он может сам; решать, что это значение означает, по-прежнему вам.
Названия инструментов и их параметры сверены 19 сентября 2026 года с README Playwright MCP и могут меняться от версии к версии. Общий порядок - открыть, посмотреть, выбрать элемент, подействовать, прочитать заново - остаётся тем же.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ