Объединение ввода CDP для согласованного hover-взаимодействия

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

BotBrowser предоставляет опцию уровня контекста для сценариев с интенсивным hover: --bot-cdp-coalesce. По умолчанию она выключена. Когда вы включаете ее для BrowserContext, обычные hover-движения мыши, отправленные через CDP, группируются по порядку короткими сериями до того, как Chromium их доставит. Каждую точку по-прежнему выбирает ваш клиент. Клики, перетаскивание, колесо, клавиатура, touch, перо и относительное движение остаются на обычных путях. Практические вопросы такие: когда включать опцию, как задавать ее для каждого контекста и как оценивать результат, не опираясь на фиксированное число событий.

Кратко

• Оставляйте опцию выключенной, если у контекста нет документированной потребности в hover мыши.
• Задайте ее до первой страницы и сравните парные запуски с одним маршрутом.
• Оценивайте видимый результат и следующее действие, а не фиксированное число событий.

Содержание

• Начните со значения по умолчанию
• Настройте один BrowserContext
• Что охватывает опция
• Последовательные вызовы и что остается за клиентом
• Проверьте парным запуском
• Где уместен BotBrowser
• Практический итог

Начните со значения по умолчанию

Большинству автоматизации браузера не нужна особая настройка ввода. Оставьте опцию выключенной, если сценарий опирается на клики, заполнение форм, навигацию с клавиатуры, прокрутку, перетаскивание, touch-жесты или перо. Значение по умолчанию сохраняет обычное поведение завершения команд CDP и не меняет сценарий, который уже выполняет свои требования к взаимодействию.

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

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

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

Настройте один BrowserContext

Задайте --bot-cdp-coalesce в интерфейсе настройки контекста, который предоставляет ваш запускающий слой BotBrowser, и примените ее до того, как контекст создаст первую страницу. Храните значение рядом с версией браузера, выбранным профилем и версией пакета автоматизации, чтобы последующая проверка воспроизвела ту же политику ввода.

Один только флаг включает поведение, явный --bot-cdp-coalesce=true делает то же самое. Используйте --bot-cdp-coalesce=false, когда общий шаблон развертывания может добавить флаг, а конкретный контекст должен остаться со значением по умолчанию. Считайте значение частью конфигурации контекста, а не тем, что переключают, пока контекст уже обслуживает страницы.

const client = await browser.target().createCDPSession();
const context = await browser.createBrowserContext();

await client.send('BotBrowser.setBrowserContextFlags', {
  browserContextId: context._contextId,
  botbrowserFlags: ['--bot-cdp-coalesce'],
});

Пример выше взят из справочника Automation Consistency и включает опцию для одного контекста. Создавайте первую страницу в этом контексте только после возврата вызова.

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

Держите настройку видимой в конфигурации запуска, а не прячьте ее в коде страницы, и записывайте, включена она или выключена, в метаданные запуска. Скрипты страницы не заменяют опцию, потому что они не могут изменить способ доставки команд мыши CDP.

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

Навигация тоже полезная граница. Hover, начатый на одном документе, не объясняет поведение указателя на документе-заменителе, поэтому дождитесь готовности новой страницы и затем выполните движение, которое нужно новому интерфейсу. Если страница или цель заменена посреди потока движений, начните новый маршрут вместо продолжения старого.

Что охватывает опция

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

Этот ввод остается на обычном пути:

• События нажатия и отпускания кнопки мыши.
• Активное движение при перетаскивании и переходы перетаскивания.
• Ввод колесом.
• Ввод с клавиатуры и набор текста.
• Touch-ввод.
• Ввод пером.
• Относительное движение мыши.

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

Состояние кнопки имеет значение. Движение, пришедшее при удерживаемой кнопке, относится к перетаскиванию или другому активному действию указателя, поэтому это не обычный hover, и оно идет обычным путем. Это правило не дает hover-группе пересечь границу между наведением на элемент и действием над ним. В справочнике CDP для Input.dispatchMouseEvent hover описан как событие mouseMoved без удерживаемой кнопки, и именно такую форму движения затрагивает эта опция.

Последовательные вызовы и что остается за клиентом

Последовательные вызовы типичны для интеграций с Puppeteer и Playwright, потому что каждый вызов ожидается до начала следующего. Это удобный контракт завершения для кликов и других отдельных действий. Для длинного hover-маршрута, однако, ожидание после каждой точки означает, что браузер редко получает несколько обычных движений рядом друг с другом.

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

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

То же различие относится к логике приложения. Подсказке, которая открывается только после задержки, по-прежнему нужна задержка, а меню, которое требует пересечь определенную область, по-прежнему требует эту область в траектории. Объединение помогает hover-движениям приходить упорядоченными группами; оно не заменяет правила взаимодействия приложения.

Клиентские библиотеки, которые разбивают одно движение на несколько промежуточных точек, например параметр steps у mouse.move в Playwright и Puppeteer, подходят естественно. Каждая промежуточная точка является обычным hover-движением, которое клиент уже выбрал, и каждая по-прежнему ожидается как отдельный вызов. Интерполяция остается задачей клиента; опция влияет только на доставку получившихся движений.

Используйте hover-шаг, чтобы добраться до элемента, а затем обычный шаг клика, чтобы его активировать, и не рассчитывайте, что hover-группировка понесет переход состояния кнопки. Для перетаскивания держите всю последовательность на обычном пути и проверяйте результат отпускания отдельно.

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

Браузер сам решает, как доставленные точки становятся событиями страницы. Страница может увидеть основное pointer-событие со списком объединенных дочерних событий, когда планирование браузера склеивает близкие движения, как описано в справочнике MDN по getCoalescedEvents. Число событий зависит от планирования, нагрузки страницы, нагрузки хоста и потока клиента, поэтому тест никогда не должен ожидать фиксированного числа событий страницы. Проверяйте видимый результат, порядок действий, завершение команд и конечную позицию указателя.

Проверьте парным запуском

Поле сравнения	Ограниченный пример	Назначение приемки
comparisonId	hover-menu-r17	Связывает два контекста с одним сценарием
contextMode	off или on	Показывает единственное измененное правило ввода
viewport	1440x900	Сохраняет сопоставимую геометрию цели
coordinateRevision	path-42	Идентифицирует упорядоченный список hover-точек
hoverState	menu-visible	Записывает требуемый результат страницы
finalPoint	x=612,y=184	Подтверждает достижение цели
followupResult	destination-loaded	Отделяет итог клика от доставки hover

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

1. Создайте контекст с выключенной опцией или с явным значением false.
2. Пройдите путь к цели тем же клиентом и с теми же координатами.
3. Запишите, появилось ли hover-состояние и достигла ли конечная позиция указателя цели.
4. Создайте отдельный контекст с включенной опцией.
5. Повторите тот же путь и запишите те же видимые результаты.

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

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

Успех означает, что нужное hover-состояние достижимо, порядок действий верен, каждая команда приходит к одному завершению, а конечная координата не потеряна. Это не означает, что каждый запуск покажет один и тот же список объединенных событий или то же число событий страницы.

Рабочая политика для одобренного настольного сценария проверки может быть короткой:

• Контексты, которые проверяют hover-меню, включают --bot-cdp-coalesce до первой страницы.
• Контексты, которые тестируют клики, формы, навигацию с клавиатуры или перетаскивание, оставляют ее выключенной, если в том же запуске нет задокументированного hover-требования.
• Общий код запуска записывает настройку вместе с версиями браузера и профиля.
• Сценарий проверяет результат hover, а затем отдельным шагом проверяет результат клика или перетаскивания.
• Заменяющий контекст начинается с явной настройки и новой проверки состояния страницы.

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

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

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

Сравнивайте контекст с включенной опцией с отдельным контекстом с выключенной опцией, начиная с одного и того же состояния страницы. Отметьте, стала ли цель видимой, достиг ли указатель намеченной конечной координаты, сработало ли следующее действие и завершилась ли каждая команда CDP один раз. Для hover-меню запишите состояние меню до клика и место назначения после него. Для подсказки запишите ее появление и исчезновение как часть маршрута.

Привязывайте каждое сравнение к одной паре браузера и профиля. Когда меняется релиз браузера, профиль, окно просмотра, пакет клиента или ревизия страницы, создайте новую базовую линию вместо того, чтобы считать старый результат прямым сравнением. Число событий используйте только как вспомогательную информацию и поднимайте сравнение на разбор, когда hover-состояние становится недостижимым, порядок действий меняется, у команды нет завершения или конечная координата неверна.

Если клиентская библиотека сообщает о завершении раньше, чем появляется видимое hover-состояние, дождитесь того состояния страницы, которое вам действительно нужно. Завершение команды CDP и готовность приложения являются разными условиями, поэтому используйте видимый сигнал приложения, поддерживаемую проверку страницы или ограниченное по времени ожидание готовности, которое относится к сценарию.

У опции нет видимого эффекта. Убедитесь, что контекст получил флаг до первой страницы, что движение является обычным hover-движением мыши и что страница действительно реагирует на hover. Последовательность клика, перетаскивания, колеса, touch, пера или относительного движения выходит за область действия опции.

Перетаскивание изменило поведение после включения опции. Разделите hover-подход и последовательность перетаскивания и начните перетаскивание обычным путем. Опция не переносит активное движение при перетаскивании.

Число событий менялось между запусками. Это ожидаемо, когда различаются планирование или нагрузка страницы. Вместо этого сравнивайте достижимое hover-состояние, порядок действий, завершения команд и конечную координату.

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

Страница все еще кажется медленной. Объединение не исправит разреженную траекторию, тяжелую страницу, медленный селектор или требование приложения к задержке. Измерьте маршрут на уровне страницы, затем скорректируйте нужный шаг, не меняя несвязанные типы ввода.

Где уместен BotBrowser

--bot-cdp-coalesce в BotBrowser является опциональной настройкой одного BrowserContext: до доставки Chromium она по порядку группирует короткие серии обычных CDP hover-движений мыши. Для иных типов ввода настройка не меняет маршрут доставки: активное перетаскивание, колесо, клавиатура, touch, перо и относительное движение обрабатываются обычным кодом Chromium. Настройка не достраивает разреженную траекторию, не заменяет задержку приложения, не исправляет готовность страницы и не гарантирует число событий, поскольку окончательным планированием управляет браузер.

BotBrowser может выполнить разрешенный hover-сценарий в BrowserContext и сравнить видимый результат contextMode=off с contextMode=on; он не создает недостающие координаты, не меняет правила приложения и не доказывает завершение бизнес-операции.

Опция не меняет идентичность браузера, сетевую маршрутизацию, cookie, хранилище, разрешения, настройку окна просмотра и данные профиля, потому что все это остается в собственных областях настройки. По смежным практикам смотрите проверку взаимодействия после смены браузера и профиля для сравнения с базовой линией, pointer-события и доступный ввод о том, как страницы обращаются с мышью, touch и пером, и планирование емкости BrowserContext о запуске нескольких контекстов в одном браузере.

--bot-cdp-coalesce дает развертыванию понятный выбор для одного узкого класса взаимодействия. По умолчанию опция остается выключенной. Включайте ее для контекста, который отправляет плотное обычное hover-движение мыши, оставляйте другие типы ввода на стандартных путях, проверяйте видимый результат и записывайте значение вместе с остальной конфигурацией контекста.

Практический итог

Включайте --bot-cdp-coalesce только для документированного hover-сценария, задавайте его до первой страницы и принимайте изменение лишь после успешного парного сравнения видимого состояния и следующего действия. BotBrowser управляет доставкой подходящих hover-движений; маршрут остается за клиентом, а корректность сценария определяет владелец приложения.

Источники

• Chrome DevTools Protocol: Input.dispatchMouseEvent
• MDN: PointerEvent.getCoalescedEvents()
• Справочник BotBrowser Automation Consistency