Снимки

Playwright MCP использует снимки дерева доступности вместо скриншотов. Каждый инструмент, взаимодействующий со страницей, возвращает дерево доступности с идентификаторами элементов (ref).

Формат снимка

- heading "todos" [level=1] [ref=e3]
- textbox "What needs to be done?" [ref=e5]
- list [ref=e8]:
  - listitem [ref=e9]:
    - checkbox "Toggle Todo" [ref=e10]
    - text: Buy groceries
  - listitem [ref=e13]:
    - checkbox "Toggle Todo" [ref=e14]
    - text: Water flowers
- contentinfo [ref=e18]:
  - text: 2 items left
  - link "All" [ref=e20]
  - link "Active" [ref=e21]
  - link "Completed" [ref=e22]

Каждый элемент получает уникальный идентификатор. Например, метка ref=e5 содержит идентификатор e5. Инструменты, выполняющие действия с элементом, принимают этот идентификатор в качестве параметра target:

browser_type  { target: "e5", text: "headphones" }
browser_click { target: "e10" }
browser_click { target: "e20" }

Указание целевых элементов

Инструменты, выполняющие действия с элементом, принимают параметр target, который поддерживает две формы:

• Идентификатор элемента — e12 или f1e12 для элемента внутри первого iframe. В снимке выводятся именно эти идентификаторы. Обычно следует передавать их.
• Селектор — любой селектор Playwright или строка локатора, например getByRole('button', { name: 'Submit' }), #submit или text=Sign in. Это удобно, если вы уже знаете нужный элемент и хотите обойтись без дополнительного запроса снимка.

Если идентификатор устарел, инструмент завершится с ошибкой Ref <ref> not found in the current page snapshot. Try capturing new snapshot.

Свойство	Описание
Формат	e с последующим числом и необязательным префиксом в виде идентификатора фрейма (e1, e15, f2e7)
Область действия	Уникальна в пределах одного снимка
Срок действия	Действительна до изменения страницы
Назначение	Назначается каждому узлу, представленному в дереве доступности, а не только интерактивным элементам

Снимки по запросу

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

Параметр	Тип	Обязательный	Описание
target	string	нет	Создать снимок только поддерева указанного элемента
depth	number	нет	Ограничить глубину дерева снимка
boxes	boolean	нет	Включить ограничивающий прямоугольник каждого элемента в формате [box=x,y,width,height] с координатами относительно области просмотра в CSS-пикселях
filename	string	нет	Сохранить снимок в файл вместо его возврата в ответе

→ browser_snapshot { depth: 2 }
→ browser_snapshot { target: "e8" }        // только поддерево списка задач
→ browser_snapshot { boxes: true }         // добавить ограничивающие прямоугольники

Режим снимков также можно задать глобально: --snapshot-mode=none отключает добавление снимков к ответам инструментов, а --snapshot-boxes включает постоянное добавление ограничивающих прямоугольников.

Поиск по снимку

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

Параметр	Тип	Обязательный	Описание
text	string	нет	Обычный текст для поиска (поиск подстроки без учёта регистра)
regex	string	нет	Регулярное выражение. По умолчанию учитывает регистр; для добавления флагов заключите выражение в косые черты, например /error/i

Укажите ровно один из параметров: text или regex.

→ browser_find { text: "Deep Target Link" }

  Found 1 match for "Deep Target Link":

  - main [ref=e2]:
    - region "Sidebar" [ref=e3]:
      - navigation "Primary" [ref=e4]:
        - list [ref=e5]:
          ...
          - listitem [ref=e16]:
            - link "Deep Target Link" [ref=e17]

→ browser_click { target: "e17" }

Пропуски в окружающем контексте обозначаются символами ....

Снимки вместе со скриншотами

Для страниц, на которых важен визуальный контекст (приложения на основе canvas, диаграммы, макеты с большим количеством изображений), используйте снимки вместе со скриншотами:

Сделай снимок дерева доступности и скриншот текущей страницы.

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

Почему снимки предпочтительнее скриншотов

	Снимки	Скриншоты
Затраты токенов	Низкие — только текст	Высокие — токены изображений
Точность	Высокая — идентификаторы элементов указывают на конкретные элементы	Приблизительная — требуется угадывать координаты
Скорость	Мгновенно — разбор текста	Медленнее — обработка моделью компьютерного зрения
Надёжность	Детерминированная — одинаковая структура = одинаковое взаимодействие	Нестабильная — изменения макета делают координаты неактуальными
Модель компьютерного зрения	Не требуется	Требуется

Рекомендации

1. Используйте идентификаторы из снимка — идентификаторы элементов из снимков надёжнее CSS-селекторов, поскольку указывают именно на тот элемент, который LLM только что увидела
2. Создавайте новый снимок после навигации — идентификаторы элементов становятся недействительными при изменении страницы
3. Используйте browser_find на больших страницах — он возвращает только соответствующее поддерево вместо полного снимка
4. Дополняйте снимки скриншотами — когда помимо структурированных данных нужен визуальный контекст
5. Проверяйте наличие диалоговых окон — если инструмент сообщает об открытом диалоговом окне, обработайте его, прежде чем переходить к другим действиям