Coalescencia de entrada CDP para un hover consistente

Los clientes de automatización suelen enviar el movimiento del ratón con un comando CDP cada vez. El cliente envía un punto, espera a que el comando termine y luego envía el siguiente. Esa secuencia es fácil de razonar y funciona bien para los clics, pero un recorrido largo de hover se convierte en una serie de movimientos aislados. Las interfaces que reaccionan al puntero, como los tooltips, las tarjetas de hover y los menús que se abren al acercarse el puntero, pueden responder de forma distinta según cómo lleguen esos movimientos al tratamiento de entrada del navegador.

BotBrowser ofrece una opción a nivel de contexto para cargas de trabajo con mucho hover: --bot-cdp-coalesce. Está desactivada por defecto. Cuando la activas para un BrowserContext, los movimientos hover simples del ratón enviados por CDP se agrupan en orden, en tramos cortos, antes de que Chromium los entregue. Tu cliente sigue eligiendo cada punto. Los clics, los arrastres, la rueda, el teclado, el táctil, el lápiz y el movimiento relativo siguen su ruta normal. Las preguntas prácticas son cuándo activar la opción, cómo fijarla por contexto y cómo juzgar el resultado sin depender de recuentos fijos de eventos.

Resumen

• Mantén la opción desactivada salvo que el contexto tenga una necesidad documentada de hover.
• Configúrala antes de la primera página y compara ejecuciones pareadas con la misma ruta.
• Evalúa el resultado visible y la acción siguiente, no un número fijo de eventos.

Contenido

• Empieza con el valor predeterminado
• Configura un BrowserContext
• Qué cubre la opción
• Llamadas seriales y lo que sigue haciendo el cliente
• Valida con una ejecución pareada
• Dónde encaja BotBrowser
• Conclusión práctica

Empieza con el valor predeterminado

Campo de decisión	Ejemplo acotado	Acción
journeyType	hover-menu	Evalúa solo movimiento hover simple
defaultOutcome	menu-visible	Conserva off si ya es fiable
targetBounds	x=560..660,y=140..220	Revisa geometría antes de activar
pageRevision	ui-r17	Repite la comparación tras un cambio

La mayoría de la automatización de navegador no necesita un ajuste especial de entrada. Deja la opción desactivada cuando una carga de trabajo se apoya en clics, formularios, navegación con teclado, desplazamiento, arrastrar y soltar, gestos táctiles o lápiz. El valor predeterminado conserva el comportamiento normal de finalización de CDP y evita cambiar un flujo que ya cumple sus requisitos de interacción.

Activa la opción solo en un contexto que envíe con frecuencia movimiento hover simple del ratón por CDP y necesite que esos puntos lleguen en grupos cortos y ordenados. Una revisión de tooltips, un menú que se abre al acercarse el puntero, una tarjeta de hover o una interfaz de escritorio sensible al puntero son casos típicos. El ajuste pertenece al contexto, de modo que una carga de trabajo puede usarlo mientras otro contexto del mismo navegador conserva el valor predeterminado.

La opción no vuelve aleatoria la trayectoria del puntero y no crea puntos de movimiento. Tu cliente sigue eligiendo las coordenadas y su orden. BotBrowser solo cambia cómo se reenvían los movimientos hover aceptados en un tramo corto, y el último punto sigue siendo la posición final que ve la página. Si la trayectoria que produce tu cliente es escasa o contiene un salto brusco, corrígelo en el cliente, porque la opción no cambia la calidad de la trayectoria.

Decide por carga de trabajo mirando el recorrido, no toda la flota. Cuenta los movimientos hover simples del recorrido, comprueba si la interfaz reacciona al acercarse el puntero y no a un clic, y pregúntate si el valor predeterminado ya produce el estado visible de forma fiable. Si el estado de hover se alcanza con fiabilidad, no hay motivo para cambiar el ajuste. Si solo se alcanza a veces, revisa primero la geometría del objetivo, la disponibilidad de la página y las coordenadas del cliente, y después prueba la opción en un contexto separado y compara las dos ejecuciones.

Configura un BrowserContext

Fija --bot-cdp-coalesce en la superficie de configuración de contexto que ofrezca tu lanzador de BotBrowser y aplícalo antes de que el contexto cree su primera página. Guarda el valor junto a la versión del navegador, la selección de perfil y la versión del paquete de automatización, para que una validación posterior pueda reproducir la misma política de entrada.

La bandera sola activa el comportamiento, y un --bot-cdp-coalesce=true explícito hace lo mismo. Usa --bot-cdp-coalesce=false cuando una plantilla de despliegue compartida pueda añadir la bandera y un contexto concreto deba conservar el valor predeterminado. Trata el valor como parte de la configuración del contexto, no como algo que se cambia mientras el contexto ya sirve páginas.

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

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

El ejemplo anterior procede de la referencia de Automation Consistency y activa la opción para un solo contexto. Crea la primera página de ese contexto solo cuando la llamada haya terminado.

Cuando un navegador aloja varios contextos, da a cada uno un ajuste deliberado. Un contexto con la opción activada no la activa en sus contextos hermanos, y un contexto nuevo debe recibir su propio valor. Esta separación permite a un equipo comparar el mismo recorrido con y sin el comportamiento dentro de un mismo navegador.

Mantén el ajuste visible en la configuración de lanzamiento en lugar de esconderlo en el código de la página, y registra si está activado o desactivado en los metadatos de la ejecución. Los scripts de página no sustituyen a la opción, porque no pueden cambiar cómo se entregan los comandos de ratón de CDP.

Cuando se recree un contexto, aplica la opción de nuevo. Una plantilla a nivel de proceso puede facilitar la repetición del valor deseado, pero el comportamiento sigue siendo una decisión por contexto. Esto importa sobre todo en sistemas que reutilizan un navegador para cuentas, inquilinos o sesiones de prueba autorizadas distintos, donde cada contexto debe llevar la política de entrada que documenta su propio flujo.

La navegación también es un límite útil. Un hover iniciado en un documento no explica el comportamiento del puntero en un documento de reemplazo, así que espera a que la nueva página esté lista y ejecuta después el movimiento que necesita la nueva interfaz. Si una página o un destino se reemplaza en mitad de un flujo de movimiento, empieza un recorrido nuevo en lugar de continuar el anterior.

Qué cubre la opción

Solo es elegible el movimiento hover simple del ratón. En la práctica, no hay ningún botón pulsado, el puntero no está en modo de movimiento relativo y el evento es un movimiento de ratón ordinario. Eso abarca el movimiento que sirve para acercarse a un objetivo, inspeccionar un estado de hover o recorrer una interfaz de escritorio.

Esta entrada conserva su ruta normal:

• Eventos de pulsar y soltar un botón del ratón.
• Movimiento de arrastre activo y transiciones de arrastre.
• Entrada de rueda.
• Entrada de teclado y escritura de texto.
• Entrada táctil.
• Entrada de lápiz.
• Movimiento relativo del ratón.

Estos límites protegen la entrada que lleva una acción discreta o que pertenece a otro tipo de dispositivo. Un clic conserva su estado de botón y su comportamiento de finalización, un arrastre conserva el orden de sus transiciones y un evento de rueda conserva la semántica de su delta y su temporización. Los recorridos móviles y táctiles deben evaluarse con entrada táctil y una ventana móvil, las interfaces de lápiz con entrada de lápiz y las aplicaciones de movimiento relativo por su ruta normal, porque un ajuste de hover de ratón no sustituye esas pruebas.

El estado del botón importa. Un movimiento que llega mientras se mantiene un botón pulsado pertenece a un arrastre o a otra acción activa del puntero, así que no es un hover simple y sigue su ruta normal. Esa regla evita que un grupo de hover cruce el límite entre señalar un control y actuar sobre él. En la referencia de CDP para Input.dispatchMouseEvent, un hover es un evento mouseMoved sin botón pulsado, que es la forma de la que se ocupa esta opción.

Llamadas seriales y lo que sigue haciendo el cliente

Las llamadas seriales son habituales en las integraciones con Puppeteer y Playwright porque cada llamada se espera antes de iniciar la siguiente. Es un contrato de finalización útil para los clics y otras acciones discretas. En un recorrido largo de hover, en cambio, esperar tras cada punto significa que el navegador rara vez recibe varios movimientos ordinarios muy juntos.

Con la opción del contexto activada, el cliente puede conservar su estilo de comandos seriales. El código que llama no necesita generar una segunda trayectoria, añadir retrasos aleatorios ni inyectar eventos de puntero desde la página. Las coordenadas existentes y el flujo de control existente siguen siendo la fuente de la interacción, y cada comando CDP conserva su contrato de finalización normal.

El cambio afecta a la entrega, no a la calidad de la trayectoria. Una trayectoria escasa sigue siendo escasa, y una trayectoria con un salto brusco sigue conteniendo ese salto. Si una página necesita una secuencia concreta de objetivos, mejora por separado las coordenadas y la temporización del cliente y valida después el resultado con el ajuste de la opción que usará el despliegue.

La misma distinción se aplica a la lógica de la aplicación. Un tooltip que se abre solo tras una permanencia sigue necesitando esa permanencia, y un menú que exige que el puntero cruce una región concreta sigue necesitando esa región en la trayectoria. La coalescencia ayuda a que los movimientos hover lleguen en grupos ordenados; no sustituye las reglas de interacción de la aplicación.

Los clientes que interpolan un movimiento en varios puntos intermedios, como la opción steps de mouse.move en Playwright y Puppeteer, encajan de forma natural. Cada punto intermedio es un movimiento hover simple que el cliente ya eligió, y cada uno se sigue esperando como una llamada propia. La interpolación sigue siendo tarea del cliente; la opción solo afecta a cómo se entregan los movimientos resultantes.

Usa un paso de hover para llegar a un control y después el paso normal de clic para activarlo, y no confíes en la agrupación de hover para transportar una transición de botón. En arrastrar y soltar, mantén la secuencia de arrastre completa en su ruta normal y verifica el resultado del soltado por separado.

Esta separación facilita leer los fallos. Si un tooltip no aparece, revisa la trayectoria de hover, la geometría del objetivo y el estado de la página. Si un clic no activa el control, revisa el foco, la detección de impacto y la secuencia del clic. Si un arrastre no termina, revisa el origen del arrastre, el destino y las reglas de aceptación de la aplicación. Un ajuste no debería convertirse en la explicación comodín de cualquier problema de puntero.

El navegador decide cómo los puntos entregados se convierten en eventos de página. Una página puede ver un evento de puntero principal con una lista de eventos hijos coalescidos cuando la planificación del navegador combina movimientos cercanos, tal como describe la referencia de MDN para getCoalescedEvents. Los recuentos de eventos varían con la planificación, el trabajo de la página, la carga del host y el flujo del cliente, así que una prueba nunca debe esperar un número fijo de eventos de página. Prueba el resultado visible, el orden de las acciones, la finalización de los comandos y la posición final del puntero.

Valida con una ejecución pareada

Campo de comparación	Ejemplo acotado	Uso de aceptación
comparisonId	hover-menu-r17	Une ambos contextos al mismo recorrido
contextMode	off u on	Muestra la única política cambiada
viewport	1440x900	Mantiene comparable la geometría
coordinateRevision	path-42	Identifica la lista hover ordenada
hoverState	menu-visible	Registra el resultado requerido
finalPoint	x=612,y=184	Confirma que se alcanzó el objetivo
followupResult	destination-loaded	Separa clic de entrega hover

Usa una página pequeña o una ruta de prueba aprobada que tenga un tooltip, un menú de hover o una tarjeta de hover y que muestre un cambio de estado visible cuando el puntero llega al objetivo. Después ejecuta el mismo recorrido dos veces, en dos contextos separados:

1. Crea un contexto con la opción desactivada, o con un valor false explícito.
2. Recorre la trayectoria hacia el objetivo con el mismo cliente y las mismas coordenadas.
3. Registra si apareció el estado de hover y si la posición final del puntero llegó al objetivo.
4. Crea un contexto separado con la opción activada.
5. Repite la misma trayectoria y registra los mismos resultados visibles.

Mantén constantes la versión del navegador, el perfil, la ventana, el estado de la página, el paquete del cliente y la lista de coordenadas, y cambia una sola variable cada vez. El número exacto de eventos de página no es un criterio de aceptación estable porque el navegador controla la planificación de eventos.

En un flujo de producción, añade un clic cuando aparezca el estado de hover y verifica el estado resultante de la página. Añade un control que no dependa del hover, como un campo de formulario o un botón normal, para confirmar que el recorrido completo sigue su ruta de entrada normal. Incluye una comprobación de arrastre, rueda, táctil o lápiz solo cuando la carga de trabajo use realmente esa entrada.

El éxito significa que el estado de hover necesario es alcanzable, el orden de las acciones es correcto, cada comando llega a una finalización y la coordenada final no se pierde. No significa que cada ejecución exponga la misma lista coalescida ni el mismo recuento de eventos de página.

Una política operativa para un flujo de revisión de escritorio aprobado puede ser breve:

• Los contextos que inspeccionan menús de hover activan --bot-cdp-coalesce antes de su primera página.
• Los contextos que prueban clics, formularios, navegación con teclado o arrastrar y soltar la dejan desactivada, salvo que la misma ejecución tenga también un requisito de hover documentado.
• El código de ejecución compartido registra el ajuste junto con las versiones del navegador y del perfil.
• El flujo valida el resultado del hover y después valida el resultado del clic o del arrastre como un paso separado.
• Un contexto de reemplazo empieza con un ajuste explícito y una comprobación nueva del estado de la página.

Esto mantiene la opción acotada y evita que un conjunto de pruebas cambie en silencio su contrato de entrada cuando cambia una plantilla de lanzamiento compartida. Los valores false explícitos son útiles en plantillas que sirven a ambos tipos de contexto.

Cuando el resultado vaya a decidir un despliegue, pide a alguien que no escribió el recorrido que revise la comparación. Un segundo lector puede confirmar que los estados visibles del registro son los que exige la aplicación y que ningún paso depende de un número concreto de eventos de página. Esa revisión cuesta poco comparada con depurar una plantilla de lanzamiento compartida después de que se haya extendido a todos los contextos.

Guarda un registro compacto de cada comparación. Incluye la versión del navegador, el identificador del perfil, la ventana, la versión de la biblioteca cliente, el ajuste del contexto, la ruta de la página, la revisión de la lista de coordenadas y la hora de la ejecución. Deja fuera el contenido de cuentas y los datos de página que el flujo no necesite. El registro nombra la política de contexto para reproducir la comparación con el mismo navegador, perfil, ventana y revisión de coordenadas.

Desde el mismo estado inicial, contrasta el recibo contextMode=on con el recibo contextMode=off. Anota si el objetivo se hizo visible, si el puntero llegó a la coordenada final prevista, si funcionó la acción siguiente y si cada comando CDP terminó una sola vez. En un menú de hover, registra el estado del menú antes del clic y el destino después. En un tooltip, registra su aparición y su desaparición como parte del recorrido.

Vincula cada comparación a un solo par de navegador y perfil. Cuando cambie la versión del navegador, el perfil, la ventana, el paquete del cliente o la revisión de la página, crea una nueva línea base en lugar de tratar el resultado antiguo como una comparación directa. Revisa los recuentos de eventos solo como información de apoyo, y escala una comparación cuando el estado de hover deje de ser alcanzable, cambie el orden de las acciones, a un comando le falte su finalización o la coordenada final sea incorrecta.

Si una biblioteca cliente informa de la finalización antes de que aparezca un estado de hover visible, espera al estado de página que realmente necesitas. La finalización de un comando CDP y la disponibilidad de la aplicación son condiciones distintas, así que usa la señal visible de la aplicación, una aserción de página compatible o una espera acotada de disponibilidad que pertenezca al flujo.

La opción no tiene efecto visible. Confirma que el contexto recibió la bandera antes de su primera página, que el movimiento es un hover simple del ratón y que la página reacciona realmente al hover. Una secuencia de clic, arrastre, rueda, táctil, lápiz o movimiento relativo queda fuera del alcance de la opción.

Un arrastre cambió de comportamiento tras activar la opción. Separa la aproximación de hover de la secuencia de arrastre e inicia el arrastre por su ruta normal. La opción no transporta el movimiento de arrastre activo.

Los recuentos de eventos cambiaron entre ejecuciones. Es lo esperado cuando difieren la planificación o la carga de la página. Compara en su lugar el estado de hover alcanzable, el orden de las acciones, las finalizaciones de los comandos y la coordenada final.

Dos contextos se comportan de forma distinta. Revisa el valor explícito de cada contexto, la versión del navegador y el perfil, la ventana, el estado de la página y la lista de coordenadas del cliente. El ajuste está aislado por contexto y no corrige las diferencias en esos otros elementos.

Una página sigue yendo lenta. La coalescencia no puede arreglar una trayectoria escasa, una página pesada, un selector lento ni un requisito de permanencia de la aplicación. Mide el recorrido a nivel de página y ajusta después el paso relevante sin cambiar otros tipos de entrada.

Dónde encaja BotBrowser

BotBrowser proporciona --bot-cdp-coalesce, una opción opt-in para un BrowserContext que agrupa en orden tramos cortos de movimientos hover simples de ratón enviados por CDP antes de que Chromium los entregue, y permite comparar un recorrido de hover con la opción activada y desactivada en contextos separados mientras clic, arrastre, rueda, teclado, táctil, lápiz y movimiento relativo siguen su ruta normal. BotBrowser no puede hacer que una trayectoria escasa o con saltos del cliente parezca natural, no sustituye las reglas de permanencia o de región de una aplicación, no arregla la disponibilidad de la página y no garantiza recuentos de eventos de página idénticos ni la misma agrupación de eventos coalescidos, porque el motor del navegador controla la planificación final de eventos.

La opción no modifica la identidad del navegador, el enrutamiento de red, las cookies, el almacenamiento, los permisos, la configuración de la ventana ni los datos del perfil, porque todo eso sigue en sus propias superficies de configuración. Para prácticas relacionadas, consulta validación de interacción tras cambios de navegador y perfil para la comparación con una línea base, eventos de puntero y entrada accesible para ver cómo tratan las páginas el ratón, el táctil y el lápiz, y planificación de capacidad de BrowserContext para ejecutar varios contextos en un mismo navegador.

--bot-cdp-coalesce da a un despliegue una opción clara para una clase de interacción muy concreta. El valor predeterminado sigue siendo desactivado. Actívala en un contexto que envíe movimiento hover simple denso, mantén los demás tipos de entrada en sus rutas estándar, valida el resultado visible y registra el valor junto con el resto de la configuración del contexto.

Conclusión práctica

Activa --bot-cdp-coalesce solo para un recorrido de hover documentado, aplícala antes de la primera página y acepta el cambio cuando el estado visible y la acción siguiente pasen en una comparación pareada. BotBrowser controla la entrega elegible; el cliente mantiene la ruta y la aplicación decide si el recorrido es correcto.

Fuentes

• Chrome DevTools Protocol: dispatchMouseEvent
• MDN: PointerEvent.getCoalescedEvents()
• Referencia de Automation Consistency de BotBrowser