Ожидания: правильный сон

Фундамент уже знаком по третьему и четвёртому урокам: каждое Query-действие само переспрашивает документ, пока условие не выполнится. Но условия — это отдельное семейство опций, и его стоит увидеть целиком. Дефолтное условие NodeReady: узлы найдены и получены из браузера. NodeVisible требует видимости — проверки offsetWidth, offsetHeight и клиентских прямоугольников; NodeNotVisible ждёт обратного. NodeEnabled дожидается, что у элемента нет атрибута disabled, NodeSelected — что элемент выбран. NodeNotPresent ждёт исчезновения: удобно после снятия оверлея загрузки. Обёртки над ними — знакомые WaitVisible, WaitNotVisible, WaitEnabled, WaitSelected, WaitNotPresent — это те же условия в виде отдельных действий. Два параметра настраивают сам механизм опроса: AtLeast задаёт, сколько узлов должно совпасть — по умолчанию один, для списка из двадцати карточек пишут AtLeast(20); RetryInterval — интервал переспросов, по умолчанию пять миллисекунд. Важно понимать, где живёт этот опрос: на стороне Go. Каждый переспрос — отдельная оценка селектора в браузере, обмен по протоколу; для условий по узлам это дёшево, а вот для сложных состояний страницы нужен инструмент, который опрашивает, не выходя из браузера, — о нём дальше.

Poll(expression, res, opts...) — ожидание произвольного условия JavaScript: из выражения собирается предикат, и он исполняется в самой странице, а не в Go-программе. Запросы вида poll element go описывают ровно этот механизм: предикат крутится в браузере, тикает по умолчанию в каждом кадре анимации — через requestAnimationFrame, — и ни один тик не стоит обмена по протоколу. Когда выражение впервые возвращает истинное значение, Poll завершается, а значение расфасовывается в res: логическое — в bool, текст — в строку, живой объект — в низкоуровневый RemoteObject; res может быть и nil, если значение не нужно. Это делает Poll универсальным: он умеет ждать не только узлы, но и данные — длину списка, значение переменной, флаг, который выставил код страницы. Таймаут по умолчанию тридцать секунд, ошибка при нём — ErrPollingTimeout. Один суровый предел: предикат не переживает навигацию — контекст исполнения страницы уничтожается, и Poll вернёт ошибку «Execution context was destroyed». Дожидаться конца загрузки новой страницы — работа Navigate и WaitReady, а Poll — про состояние внутри одной страницы.

Когда условие сложнее одного выражения, его оформляют функцией: PollFunction(pageFunction, res, opts...) оборачивает её в вызов с аргументами — return (функция)(...args). Аргументы передаются опцией WithPollingArgs: предикат вида (n) => document.querySelectorAll('.card').length >= n вместе с WithPollingArgs(20) ждёт, пока карточек станет не меньше двадцати; значения едут как есть — числа, строки, структуры, закодированные в JSON. Вторая степень свободы — режим опроса. Дефолтный тик по кадрам анимации — самый частый и самый прожорливый по CPU страницы; он нужен, когда условие завязано на стили и размеры. WithPollingInterval(interval) переводит опрос на таймер: раз в двести пятьдесят миллисекунд — разумная точка для медленных состояний вроде загрузки данных. WithPollingMutation ждёт событий DOM: предикат проверяется один раз, а дальше — на каждое изменение дерева; это самый экономный режим, и у него есть поучительная история: ранние версии мутирующего опроса умели пропускать таймаут, если страница молчала, поэтому сниппет исполнения доработали страховкой, а тесты библиотеки проверяют случай «таймаут без мутаций». Привычка задавать WithPollingTimeout явно от этого только надёжнее. Опция WithPollingInFrame переносит предикат в указанный фрейм — узлы фрейма достают действием Nodes, и это единственный путь, когда условие живёт внутри iframe.

Условия и предикаты закрывают вопрос «когда продолжать», но иногда в сам момент готовности нужно что-то сделать: посчитать узлы, вынуть из них данные, запустить свою функцию ровно тогда, когда страница доехала. Для этого у Query есть крючок After, а у библиотеки — обёртка QueryAfter(sel, f, opts...): селектор опрашивается, как обычно, условия выполняются, и затем вызывается ваша функция f с контекстом, идентификатором контекста исполнения и срезом найденных узлов. Сигнатура строгая: func(ctx context.Context, execCtx runtime.ExecutionContextID, nodes ...*cdp.Node) error — вернуть ошибку значит уронить весь Run, как от любого действия. Именно на этом крючке построены все Query-действия библиотеки: Text, Click и SetValue — это QueryAfter со своей функцией внутри, и теперь вы можете собрать в том же стиле собственное действие. Типовые применения: дожидаться AtLeast(20) карточек и одним махом собрать их узлы для дальнейшей работы; выполнить условие NodeVisible и сразу прокрутить узел; совместить своё ожидание с существующими опциями Query — ByQueryAll, AtLeast, RetryInterval. Это низкоуровневый инструмент, и брать его стоит, когда готовых действий уже не хватает, — но знание, что весь слой Query стоит на нём, делает библиотеку прозрачной. Крючок After многоразовый: функций можно повесить несколько, и исполнятся они по порядку добавления, а QueryAfter — лишь обёртка над одной из них. Ещё две детали из недр Query: порог AtLeast проверяется до условий видимости, поэтому с AtLeast(20) прогон честно крутится, пока карточек меньше двадцати; а битый селектор, скажем со случайным двоеточием, не уходит в вечный переспрос — браузер отвечает ошибкой DOM, и она сразу выезжает наверх.

У каждого ожидания есть верхняя граница, и её выбор — отдельное решение. У Poll и PollFunction — WithPollingTimeout: по умолчанию тридцать секунд, ноль отключает таймаут совсем. У дедлайна контекста — context.WithTimeout, знакомый по третьему уроку: он отсекает весь прогон, включая навигацию и действия. Правило их совместной жизни: таймаут предиката должен быть заметно меньше дедлайна контекста, иначе внешний дедлайн ударит первым, и вы получите не внятную ошибку ErrPollingTimeout, а безликую context deadline exceeded, из которой не видно, какое из условий не доехало. Разумная связка для обхода: контексту — бюджет страницы, скажем двадцать секунд, предикату — пятнадцать; тогда при отказе ошибка укажет на конкретное ожидание. Второе правило — таймауты задаются явно даже там, где есть дефолт: тридцать секунд — значение для человека за консолью, а не для обхода в тысячу страниц, где три зависших предиката стоят минуту времени воркера. Ноль, отключающий таймаут, — инструмент осознанный: он уместен в интерактивной сессии, когда вы смотрите на страницу глазами и готовы прервать сами, и опасен в автоматике, где превращает зависание в вечное.