Coalescence de saisie CDP pour un survol cohérent

Les clients d'automatisation envoient généralement le mouvement de la souris une commande CDP à la fois. Le client envoie un point, attend la fin de la commande, puis envoie le suivant. Cette séquence est simple à raisonner et convient bien aux clics, mais un long parcours de survol devient une suite de mouvements isolés. Les interfaces qui réagissent au pointeur, comme les infobulles, les cartes de survol et les menus qui s'ouvrent à l'approche du pointeur, peuvent réagir différemment selon la manière dont ces mouvements parviennent au traitement de la saisie du navigateur.

BotBrowser fournit une option au niveau du contexte pour les charges de travail riches en survols : --bot-cdp-coalesce. Elle est désactivée par défaut. Lorsque vous l'activez pour un BrowserContext, les mouvements de survol simples de la souris envoyés par CDP sont regroupés dans l'ordre, par courtes séquences, avant que Chromium ne les livre. Votre client continue de choisir chaque point. Les clics, les glissements, la molette, le clavier, le tactile, le stylet et le mouvement relatif gardent leur chemin normal. Les questions pratiques sont de savoir quand activer l'option, comment la définir par contexte et comment juger le résultat sans dépendre de nombres d'événements fixes.

Résumé

• Laissez l'option désactivée sauf si le contexte a un besoin documenté de survol de souris.
• Configurez-la avant la première page et comparez deux exécutions avec le même parcours.
• Évaluez le résultat visible et l'action suivante, pas un nombre fixe d'événements.

Sommaire

• Commencez par la valeur par défaut
• Configurez un BrowserContext
• Ce que couvre l'option
• Appels sériels et ce que le client garde à sa charge
• Validez avec une exécution appariée
• Où BotBrowser s'insère
• Conclusion pratique

Commencez par la valeur par défaut

Champ de décision	Exemple borné	Action
journeyType	hover-menu	Évaluer seulement le survol simple
defaultOutcome	menu-visible	Garder off s’il est déjà fiable
targetBounds	x=560..660,y=140..220	Vérifier la géométrie avant activation
pageRevision	ui-r17	Rejouer après une modification

La plupart des automatisations de navigateur n'ont pas besoin d'un réglage de saisie particulier. Laissez l'option désactivée lorsqu'une charge de travail repose sur des clics, des formulaires, la navigation au clavier, le défilement, le glisser-déposer, les gestes tactiles ou le stylet. La valeur par défaut conserve le comportement normal de fin de commande CDP et évite de modifier un flux qui répond déjà à ses exigences d'interaction.

Activez l'option uniquement pour un contexte qui envoie fréquemment des mouvements de survol simples de la souris par CDP et qui a besoin que ces points soient livrés en groupes courts et ordonnés. Une revue d'infobulles, un menu qui s'ouvre à l'approche du pointeur, une carte de survol ou une interface de bureau sensible au pointeur en sont des cas typiques. Le réglage appartient au contexte : une charge de travail peut l'utiliser pendant qu'un autre contexte du même navigateur garde la valeur par défaut.

L'option ne rend pas la trajectoire du pointeur aléatoire et ne crée pas de points de mouvement. Votre client continue de choisir les coordonnées et leur ordre. BotBrowser ne modifie que la manière dont les mouvements de survol acceptés sont transmis dans une courte séquence, et le dernier point reste la position finale vue par la page. Si la trajectoire produite par votre client est clairsemée ou contient un saut brusque, corrigez-la côté client, car l'option ne change pas la qualité de la trajectoire.

Décidez par charge de travail en observant le parcours, et non l'ensemble du parc. Comptez les mouvements de survol simples du parcours, vérifiez si l'interface réagit à l'approche du pointeur plutôt qu'à un clic, et demandez-vous si la valeur par défaut produit déjà l'état visible de façon fiable. Si l'état de survol est atteint de façon fiable, il n'y a aucune raison de modifier le réglage. S'il n'est atteint qu'occasionnellement, vérifiez d'abord la géométrie de la cible, la disponibilité de la page et les coordonnées du client, puis essayez l'option dans un contexte séparé et comparez les deux exécutions.

Configurez un BrowserContext

Définissez --bot-cdp-coalesce dans la surface de configuration de contexte que fournit votre lanceur BotBrowser, et appliquez-la avant que le contexte ne crée sa première page. Conservez la valeur à côté de la version du navigateur, du profil choisi et de la version du paquet d'automatisation, afin qu'une validation ultérieure puisse reproduire la même politique de saisie.

L'option seule active le comportement, et un --bot-cdp-coalesce=true explicite fait de même. Utilisez --bot-cdp-coalesce=false lorsqu'un modèle de déploiement partagé peut ajouter l'option et qu'un contexte particulier doit garder la valeur par défaut. Considérez la valeur comme faisant partie de la configuration du contexte, et non comme quelque chose à changer alors que le contexte sert déjà des pages.

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

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

L'exemple ci-dessus provient de la référence Automation Consistency et active l'option pour un seul contexte. Créez la première page de ce contexte seulement après le retour de l'appel.

Lorsqu'un navigateur héberge plusieurs contextes, donnez à chacun un réglage délibéré. Un contexte pour lequel l'option est activée ne l'active pas pour ses voisins, et un nouveau contexte doit recevoir sa propre valeur. Cette séparation permet à une équipe de comparer le même parcours avec et sans ce comportement au sein d'un même navigateur.

Gardez le réglage visible dans la configuration de lancement plutôt que de le cacher dans le code de la page, et notez s'il est activé ou désactivé dans les métadonnées d'exécution. Les scripts de page ne remplacent pas l'option, car ils ne peuvent pas changer la manière dont les commandes souris CDP sont livrées.

Lorsqu'un contexte est recréé, appliquez de nouveau l'option. Un modèle au niveau du processus peut faciliter la répétition de la valeur souhaitée, mais le comportement reste un choix par contexte. Cela compte surtout pour les systèmes qui réutilisent un navigateur pour des comptes, des locataires ou des sessions de test autorisées distincts, où chaque contexte doit porter la politique de saisie que documente son propre flux.

La navigation est aussi une frontière utile. Un survol commencé sur un document n'explique pas le comportement du pointeur sur un document de remplacement : attendez que la nouvelle page soit prête, puis exécutez le mouvement dont la nouvelle interface a besoin. Si une page ou une cible est remplacée au milieu d'un flux de mouvement, démarrez un nouveau parcours au lieu de poursuivre l'ancien.

Ce que couvre l'option

Seul le mouvement de survol simple de la souris est éligible. Concrètement, aucun bouton n'est enfoncé, le pointeur n'est pas en mode de mouvement relatif et l'événement est un déplacement ordinaire de la souris. Cela couvre le mouvement utilisé pour approcher une cible, inspecter un état de survol ou traverser une interface de bureau.

Cette saisie garde son chemin normal :

• Événements d'appui et de relâchement d'un bouton de la souris.
• Mouvement de glissement actif et transitions de glissement.
• Saisie à la molette.
• Saisie au clavier et entrée de texte.
• Saisie tactile.
• Saisie au stylet.
• Mouvement relatif de la souris.

Ces limites protègent la saisie qui porte une action discrète ou qui relève d'un autre type d'appareil. Un clic conserve son état de bouton et son comportement de fin, un glissement conserve l'ordre de ses transitions, et un événement de molette conserve la sémantique de son delta et de sa temporisation. Les parcours mobiles et tactiles doivent être évalués avec une saisie tactile et une fenêtre mobile, les interfaces à stylet avec une saisie au stylet et les applications à mouvement relatif par leur chemin normal, car un réglage de survol souris ne remplace pas ces tests.

L'état des boutons compte. Un mouvement qui arrive alors qu'un bouton est maintenu appartient à un glissement ou à une autre action active du pointeur : ce n'est donc pas un survol simple, et il suit son chemin normal. Cette règle empêche un groupe de survol de franchir la frontière entre viser un contrôle et agir dessus. Dans la référence CDP de Input.dispatchMouseEvent, un survol est un événement mouseMoved sans bouton maintenu, ce qui correspond à la forme dont cette option s'occupe.

Appels sériels et ce que le client garde à sa charge

Les appels sériels sont courants dans les intégrations Puppeteer et Playwright, car chaque appel est attendu avant que le suivant ne démarre. C'est un contrat de fin utile pour les clics et les autres actions discrètes. Pour un long parcours de survol, en revanche, attendre après chaque point signifie que le navigateur reçoit rarement plusieurs mouvements ordinaires rapprochés.

Avec l'option de contexte activée, le client peut conserver son style de commandes sérielles. L'appelant n'a pas besoin de générer une seconde trajectoire, d'ajouter des délais aléatoires ou d'injecter des événements de pointeur côté page. Les coordonnées existantes et le flux de contrôle existant restent la source de l'interaction, et chaque commande CDP conserve son contrat de fin normal.

Le changement concerne la livraison, pas la qualité de la trajectoire. Une trajectoire clairsemée reste clairsemée, et une trajectoire avec un saut brusque contient toujours ce saut. Si une page exige une séquence de cibles particulière, améliorez séparément les coordonnées et le rythme du client, puis validez le résultat avec le réglage d'option que le déploiement utilisera.

La même distinction s'applique à la logique de l'application. Une infobulle qui ne s'ouvre qu'après un temps de maintien a toujours besoin de ce temps, et un menu qui exige que le pointeur traverse une région précise a toujours besoin de cette région dans la trajectoire. La coalescence aide les mouvements de survol à arriver en groupes ordonnés ; elle ne remplace pas les règles d'interaction de l'application.

Les bibliothèques clientes qui interpolent un mouvement en plusieurs points intermédiaires, comme l'option steps de mouse.move dans Playwright et Puppeteer, s'y prêtent naturellement. Chaque point intermédiaire est un mouvement de survol simple que le client a déjà choisi, et chacun reste attendu comme un appel distinct. L'interpolation reste la tâche du client ; l'option n'affecte que la livraison des mouvements obtenus.

Utilisez une étape de survol pour atteindre un contrôle, puis l'étape de clic normale pour l'activer, et ne comptez pas sur le regroupement de survol pour porter une transition de bouton. Pour le glisser-déposer, gardez la séquence de glissement complète sur son chemin normal et vérifiez le résultat du dépôt séparément.

Cette séparation rend les échecs plus lisibles. Si une infobulle n'apparaît pas, examinez la trajectoire de survol, la géométrie de la cible et l'état de la page. Si un clic n'active pas le contrôle, examinez le focus, la détection de cible et la séquence du clic. Si un glissement ne se termine pas, examinez la source du glissement, la destination et les règles d'acceptation de l'application. Un seul réglage ne doit pas devenir l'explication universelle de tous les problèmes de pointeur.

Le navigateur décide comment les points livrés deviennent des événements de page. Une page peut voir un événement de pointeur principal accompagné d'une liste d'événements enfants coalescés lorsque l'ordonnancement du navigateur combine des mouvements proches, comme le décrit la référence MDN de getCoalescedEvents. Les nombres d'événements varient selon l'ordonnancement, le travail de la page, la charge de l'hôte et le flux du client : un test ne doit donc jamais attendre un nombre fixe d'événements de page. Testez le résultat visible, l'ordre des actions, la fin des commandes et la position finale du pointeur.

Validez avec une exécution appariée

Champ de comparaison	Exemple borné	Usage d’acceptation
comparisonId	hover-menu-r17	Lie les deux contextes au même parcours
contextMode	off ou on	Montre la seule règle modifiée
viewport	1440x900	Garde une géométrie comparable
coordinateRevision	path-42	Identifie la liste de survol ordonnée
hoverState	menu-visible	Consigne le résultat requis
finalPoint	x=612,y=184	Confirme l’atteinte de la cible
followupResult	destination-loaded	Sépare clic et livraison du survol

Utilisez une petite page ou une route de test approuvée qui comporte une infobulle, un menu de survol ou une carte de survol et qui expose un changement d'état visible lorsque le pointeur atteint la cible. Exécutez ensuite le même parcours deux fois, dans deux contextes séparés :

1. Créez un contexte avec l'option désactivée, ou avec une valeur false explicite.
2. Parcourez la trajectoire vers la cible avec le même client et les mêmes coordonnées.
3. Notez si l'état de survol est apparu et si la position finale du pointeur a atteint la cible.
4. Créez un contexte séparé avec l'option activée.
5. Répétez la même trajectoire et notez les mêmes résultats visibles.

Gardez constants la version du navigateur, le profil, la fenêtre, l'état de la page, le paquet client et la liste de coordonnées, et ne changez qu'une variable à la fois. Le nombre exact d'événements de page n'est pas un critère d'acceptation stable, car le navigateur contrôle l'ordonnancement des événements.

Pour un flux de production, ajoutez un clic une fois l'état de survol apparu et vérifiez l'état de page obtenu. Ajoutez un contrôle qui ne dépend pas du survol, comme un champ de formulaire ou un bouton ordinaire, pour confirmer que le parcours global suit toujours son chemin de saisie normal. N'incluez une vérification de glissement, de molette, de tactile ou de stylet que si la charge de travail utilise réellement cette saisie.

Le succès signifie que l'état de survol requis est atteignable, que l'ordre des actions est correct, que chaque commande atteint une fin et que la coordonnée finale n'est pas perdue. Il ne signifie pas que chaque exécution expose la même liste coalescée ou le même nombre d'événements de page.

Une politique d'exploitation pour un flux de revue de bureau approuvé peut rester courte :

• Les contextes qui inspectent des menus de survol activent --bot-cdp-coalesce avant leur première page.
• Les contextes qui testent les clics, les formulaires, la navigation au clavier ou le glisser-déposer la laissent désactivée, sauf si la même exécution a aussi une exigence de survol documentée.
• Le code d'exécution partagé note le réglage avec les versions du navigateur et du profil.
• Le flux valide le résultat du survol, puis valide le résultat du clic ou du glissement comme une étape séparée.
• Un contexte de remplacement démarre avec un réglage explicite et une nouvelle vérification de l'état de la page.

Cela garde l'option ciblée et empêche une suite de tests de changer silencieusement son contrat de saisie lorsqu'un modèle de lancement partagé évolue. Les valeurs false explicites sont utiles dans les modèles qui servent les deux types de contexte.

Lorsque le résultat doit orienter une décision de déploiement, faites relire la comparaison par une personne qui n'a pas écrit le parcours. Un second lecteur peut confirmer que les états visibles du relevé sont ceux qu'exige l'application et qu'aucune étape ne dépend d'un nombre précis d'événements de page. Cette relecture coûte peu comparée au débogage d'un modèle de lancement partagé une fois qu'il s'est propagé à tous les contextes.

Gardez un relevé compact pour chaque comparaison. Incluez la version du navigateur, l'identifiant du profil, la fenêtre, la version de la bibliothèque cliente, le réglage du contexte, la route de la page, la révision de la liste de coordonnées et l'heure de l'exécution. Laissez de côté le contenu des comptes et les données de page dont le flux n'a pas besoin. Le relevé nomme la politique du contexte pour reproduire la comparaison avec le même navigateur, profil, fenêtre et révision de coordonnées.

Comparez le contexte où l'option est activée à un contexte séparé où elle est désactivée, à partir du même état initial de la page. Notez si la cible est devenue visible, si le pointeur a atteint la coordonnée finale prévue, si l'action suivante a fonctionné et si chaque commande CDP s'est terminée une seule fois. Pour un menu de survol, notez l'état du menu avant le clic et la destination après. Pour une infobulle, notez son apparition et sa disparition dans le cadre du parcours.

Rattachez chaque comparaison à une seule paire navigateur et profil. Lorsque la version du navigateur, le profil, la fenêtre, le paquet client ou la révision de la page change, créez une nouvelle référence au lieu de traiter l'ancien résultat comme une comparaison directe. Ne considérez les nombres d'événements que comme une information d'appoint, et escaladez une comparaison lorsque l'état de survol devient inatteignable, que l'ordre des actions change, qu'une commande n'a pas de fin ou que la coordonnée finale est erronée.

Si une bibliothèque cliente signale la fin d'une commande avant qu'un état de survol visible n'apparaisse, attendez l'état de page dont vous avez réellement besoin. La fin d'une commande CDP et la disponibilité de l'application sont des conditions distinctes : utilisez le signal visible de l'application, une assertion de page prise en charge ou une attente de disponibilité bornée qui appartient au flux.

L'option n'a aucun effet visible. Vérifiez que le contexte a reçu l'option avant sa première page, que le mouvement est bien un survol simple de la souris et que la page réagit réellement au survol. Une séquence de clic, de glissement, de molette, de tactile, de stylet ou de mouvement relatif sort du périmètre de l'option.

Un glissement a changé de comportement après l'activation de l'option. Séparez l'approche de survol de la séquence de glissement et démarrez le glissement par son chemin normal. L'option ne porte pas le mouvement de glissement actif.

Les nombres d'événements ont changé d'une exécution à l'autre. C'est normal lorsque l'ordonnancement ou la charge de la page diffèrent. Comparez plutôt l'état de survol atteignable, l'ordre des actions, la fin des commandes et la coordonnée finale.

Deux contextes se comportent différemment. Vérifiez la valeur explicite de chaque contexte, la version du navigateur et le profil, la fenêtre, l'état de la page et la liste de coordonnées du client. Le réglage est isolé par contexte et ne corrige pas les écarts sur ces autres éléments.

Une page reste lente. La coalescence ne peut pas réparer une trajectoire clairsemée, une page lourde, un sélecteur lent ni une exigence de maintien de l'application. Mesurez le parcours au niveau de la page, puis ajustez l'étape concernée sans modifier les autres types de saisie.

Où BotBrowser s'insère

BotBrowser fournit --bot-cdp-coalesce, une option facultative pour un BrowserContext qui regroupe dans l'ordre de courtes séquences de mouvements de survol simples de la souris envoyés par CDP avant que Chromium ne les livre, et permet de comparer un parcours de survol avec l'option activée et désactivée dans des contextes séparés pendant que clic, glissement, molette, clavier, tactile, stylet et mouvement relatif gardent leur chemin normal. BotBrowser ne peut pas rendre naturelle une trajectoire clairsemée ou saccadée du client, ne remplace pas les règles de maintien ou de région d'une application, ne corrige pas la disponibilité de la page et ne garantit pas des nombres d'événements de page identiques ni le même regroupement d'événements coalescés, car le moteur du navigateur contrôle l'ordonnancement final des événements.

L'option ne modifie ni l'identité du navigateur, ni le routage réseau, ni les cookies, ni le stockage, ni les autorisations, ni la configuration de la fenêtre, ni les données du profil, car tout cela reste dans ses propres surfaces de configuration. Pour des pratiques voisines, consultez la validation des interactions après un changement de navigateur ou de profil pour la comparaison à une référence, les événements de pointeur et la saisie accessible pour la manière dont les pages traitent la souris, le tactile et le stylet, et la planification de capacité des BrowserContext pour exécuter plusieurs contextes dans un même navigateur.

--bot-cdp-coalesce offre à un déploiement un choix clair pour une classe d'interaction très précise. La valeur par défaut reste désactivée. Activez-la pour un contexte qui envoie des mouvements de survol simples denses, gardez les autres types de saisie sur leurs chemins standard, validez le résultat visible et notez la valeur avec le reste de la configuration du contexte.

Conclusion pratique

Activez --bot-cdp-coalesce uniquement pour un parcours de survol documenté, avant la première page, et acceptez le changement lorsque l'état visible et l'action suivante réussissent dans une comparaison appariée. BotBrowser contrôle la livraison éligible; le client garde le parcours et l'application décide si le parcours est correct.

Sources

• Chrome DevTools Protocol: dispatchMouseEvent
• MDN: PointerEvent.getCoalescedEvents()
• Référence Automation Consistency de BotBrowser