Politique de ratio de pixels de l'appareil avec --bot-dpr

La politique de ratio de pixels relève de l'affichage, pas d'un réglage de rendu : un MacBook Retina annonce 2 dans window.devicePixelRatio, un portable de bureau annonce le plus souvent 1 ou 1.25, et un profil préparé pour l'un ne doit pas hériter silencieusement de la valeur de l'autre. BotBrowser expose --bot-dpr avec les modes profile, real et advanced pour que l'origine de ce nombre figure dans la commande de lancement, tandis que le CSS responsif de la page et l'usage que le site fait de la valeur restent l'affaire du site.

Pour la question distincte du cycle de vie, consultez l'émulation de fenêtre active et l'état de visibilité.

TL;DR

• --bot-dpr=profile est la valeur par défaut : l'échelle d'affichage du profil est utilisée, donc DPR, fenêtre et écran restent solidaires si vous ajoutez --bot-window=profile et --bot-screen=profile.
• --bot-dpr=real suit le moniteur de l'hôte, ce qui convient à un poste d'assistance ou à une revue de design où l'écran du poste de travail est l'expérience voulue.
• advanced conserve le DPR du profil et applique des ajustements de mise en page limités ; il est expérimental, désactivé par défaut et ne constitue pas un mode de plus grande précision.
• Choisissez le mode avant qu'un BrowserContext ne crée sa première page ou son premier worker, car les pages existantes gardent le comportement établi au démarrage de leur contexte.
• Consignez cinq champs avec chaque exécution : version de BotBrowser, profil, mode DPR, fenêtre d'affichage et cible de capture.

Sommaire

• Pourquoi l'échelle d'affichage compte pour une page
• Trois modes : profile, real et advanced
• Garder le DPR avec la fenêtre et l'écran
• Sessions par contexte
• Valider et consigner une politique
• Déployer et maintenir une politique

Regarder la vidéo

Cette vidéo en anglais suit un seul nombre, window.devicePixelRatio. Elle passe en revue les valeurs courantes de l'article et ses trois modes (profile, real et advanced), puis demande à un vrai navigateur d'où vient son propre nombre : une page de laboratoire locale est lue dans la console DevTools de Chrome standard sur un runner Ubuntu (DPR 1 sur un écran de 1920 par 984 ; la requête 2dppx ne correspond pas), et un runner Windows montre l'interface de DevTools zoomée de 1,25 à 1,75, soit l'échelle de l'outil lui-même, pas celle de la page. Elle se termine sur la règle par contexte et les cinq champs à noter à côté de chaque exécution. Aucun profil BotBrowser n'est chargé dans les enregistrements : les modes de --bot-dpr sont cités depuis cet article, pas exécutés. L'audio est en anglais.

Pourquoi l'échelle d'affichage compte pour une page

window.devicePixelRatio indique à une page combien de pixels physiques se trouvent derrière un pixel CSS. Un ordinateur portable de bureau annonce généralement 1 ou 1.25, un MacBook Retina annonce 2 et de nombreux téléphones annoncent 3. La même valeur alimente les media queries de résolution CSS, la sélection d'images adaptatives et les calculs de mise en page, si bien qu'elle voyage avec le reste de la configuration d'affichage : taille d'écran, taille de fenêtre et profondeur de couleur.

Lorsqu'un profil décrit un affichage et que le moniteur de l'hôte en est un autre, la session porte deux configurations d'affichage à la fois. L'option --bot-dpr rend ce choix explicite au lieu de le laisser à la machine sur laquelle le navigateur s'exécute. BotBrowser peut fixer explicitement le ratio de pixels de l'appareil d'un profil dans un contexte contrôlé ; il ne peut pas changer la façon dont un site réagit à cette valeur.

Dans un navigateur ordinaire, la valeur n'est pas toujours constante. MDN indique qu'elle change lorsque l'utilisateur zoome la page, et sur de nombreux postes de bureau elle change aussi lorsqu'une fenêtre passe sur un moniteur d'échelle différente. Une page peut surveiller ces changements avec une media query de résolution, ce qui explique qu'une application puisse redessiner des images ou des canevas après la mise à jour de la valeur. Pour un flux reproductible, cela compte concrètement : une session avec une seule source d'échelle documentée donne à la page une valeur de départ stable, et une différence ultérieure entre deux exécutions renvoie alors à la page ou à l'hôte plutôt qu'à un réglage d'affichage non consigné.

Les pages ne lisent pas le DPR isolément. Les requêtes de résolution CSS peuvent choisir une autre feuille de style quand l'échelle change. Les images adaptatives peuvent choisir une autre source. Les dimensions du canevas, les calculs du viewport visuel et les commandes de zoom de l'application peuvent aussi dépendre du rapport entre pixels CSS et pixels physiques.

Les profils mobiles utilisent couramment un DPR plus élevé que les profils de bureau. L'essentiel n'est pas qu'un nombre plus grand soit meilleur. L'essentiel est que la valeur soit cohérente avec la famille d'appareils visée et avec les dimensions d'écran fournies par le même profil. Ne copiez pas le DPR d'un mobile dans un profil de bureau uniquement pour qu'une page utilise une image de plus haute résolution.

Trois modes : profile, real et advanced

Mode	À utiliser quand	Résultat
profile	Le profil doit définir la configuration d'affichage	Utilise l'échelle d'affichage du profil. Valeur par défaut.
real	La session doit suivre l'affichage de l'hôte	Utilise l'échelle d'affichage de l'hôte.
advanced	Un flux existant a besoin d'ajustements de mise en page limités tout en gardant le DPR du profil	Mode de compatibilité expérimental. Non activé par défaut.

profile est la valeur par défaut, donc les lancements existants conservent leur comportement actuel. Ne définissez un autre mode que lorsque le déploiement l'exige.

Commencez par le modèle d'affichage que le profil doit représenter. Un navigateur basé sur un profil porte normalement un système d'exploitation cible, une famille de viewport, des dimensions d'écran et des capacités d'entrée. L'échelle d'affichage appartient à ce même groupe. Si le profil représente un ordinateur portable ou un téléphone, profile garde l'échelle liée au reste des données du profil.

Utilisez real pour un poste de travail où le moniteur physique fait partie de l'expérience de l'utilisateur. C'est courant pour un opérateur de support, une revue de conception ou une session de navigateur qui doit suivre les réglages d'accessibilité de l'hôte. Dans ces cas, l'affichage de l'hôte est la source de vérité. real expose l'échelle d'affichage de l'hôte, qui peut différer de celle du profil sélectionné ; ne le choisissez donc que si cette configuration basée sur l'hôte est voulue.

advanced est expérimental et n'est pas activé par défaut. Il conserve le DPR du profil et applique des ajustements de mise en page limités ; il ne remet pas à l'échelle toute la page et ne garantit pas des mesures de mise en page ou des captures concordantes. Ce n'est pas un mode de plus grande précision, et des valeurs de DPR différentes entre l'hôte et le profil ne suffisent pas à elles seules à l'activer. Vérifiez la mise en page et les captures concernées sur l'hôte visé avant de l'adopter, et revenez à profile si les ajustements introduisent des incohérences.

Les systèmes de bureau peuvent fonctionner avec des moniteurs aux réglages d'échelle différents. Un hôte peut annoncer une valeur alors que le profil a été préparé pour une autre. profile est utile lorsque le profil doit rester stable d'une machine à l'autre. real est utile lorsque le poste de travail actuel doit piloter l'affichage. Les deux choix sont valides, avec des sources de vérité différentes.

Garder le DPR avec la fenêtre et l'écran

DPR, fenêtre et écran forment une seule configuration d'affichage. Modifiez-les ensemble, pas un par un d'une exécution à l'autre.

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-dpr=profile \
  --bot-window=profile \
  --bot-screen=profile

Les sessions de bureau avec interface utilisent par défaut les dimensions de fenêtre et d'écran de l'hôte. Si une session avec interface doit annoncer les dimensions du profil, définissez --bot-window=profile et --bot-screen=profile à côté de --bot-dpr=profile. Le guide écran et fenêtre couvre les options de taille, et l'émulation d'appareils couvre les profils mobiles.

Une session de poste de travail qui représente le moniteur de l'opérateur peut à la place utiliser l'affichage de l'hôte pour les trois valeurs :

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-dpr=real \
  --bot-window=real \
  --bot-screen=real

Les valeurs exactes de fenêtre et d'écran dépendent du profil et du déploiement. Les deux exemples montrent la relation entre les trois politiques. Choisissez des valeurs prises en charge par la version de BotBrowser installée et gardez le même ensemble pour les pages comparées.

Les déploiements sans interface demandent la même rigueur. Sans moniteur visible, la source d'affichage reste un choix : décidez si la session représente l'affichage du profil ou un affichage de l'hôte, et écrivez les options explicitement au lieu d'hériter de ce que la machine fournit.

Lorsqu'une session passe d'un poste de travail local à une machine distante, décidez si le navigateur représente l'affichage de l'opérateur ou l'affichage cible du profil. Faites de cette décision une partie de la configuration de déploiement. Évitez de choisir le mode à partir d'une variable d'environnement qui change silencieusement d'une machine à l'autre. Un argument de lancement visible facilite l'audit du comportement obtenu. Un test local qui utilise real peut donner un résultat différent sur une machine sans moniteur physique, et un test qui utilise profile peut différer d'un test de poste de travail lié à un moniteur. Aucun des deux résultats n'est faux, mais la différence doit être voulue.

Sessions par contexte

Avec les empreintes par contexte, définissez --bot-dpr avant que le BrowserContext crée sa première page ou son premier worker. La politique choisie reste associée au comportement d'affichage et de mise en page de ce contexte. Les pages existantes gardent le comportement établi au démarrage de leur contexte ; modifier plus tard une commande de lancement ne les met donc pas à jour. Fermez et recréez un contexte lorsque la configuration d'affichage doit changer.

Utilisez le même mode pour le navigateur principal et pour un profil par contexte lorsqu'ils représentent le même appareil. Choisissez un mode différent uniquement lorsque le contexte représente volontairement un autre environnement d'affichage. Faire évoluer les contextes de navigateur couvre le cycle de vie plus large des contextes.

Si plusieurs contextes représentent la même famille d'appareils, utilisez la même politique de DPR et des réglages de fenêtre et d'écran cohérents. S'ils représentent volontairement des appareils différents, gardez les réglages de chaque contexte ensemble dans son propre enregistrement de configuration. Ne partagez pas un contexte entre un affichage basé sur le profil et un affichage basé sur l'hôte lorsque l'application s'appuie sur une mise en page adaptative stable.

Les groupes de contextes doivent aussi consigner le mode choisi. Cela aide à expliquer pourquoi deux pages ayant la même URL peuvent recevoir un balisage adaptatif différent, et empêche un worker d'hériter d'un contexte créé pour une autre politique d'affichage.

Un service qui démarre de nombreux contextes doit définir le mode dans sa configuration de lancement partagée et le copier dans les options de création de chaque contexte. Journalisez le mode choisi au démarrage sans journaliser le contenu du profil. Gardez un seul responsable pour les valeurs par défaut de la ligne de commande utilisées par les scripts d'enveloppe et les services de lancement. Si plusieurs scripts choisissent chacun leur valeur par défaut, une modification de maintenance peut scinder un groupe de contextes en politiques d'affichage différentes.

Lorsqu'un script d'enveloppe construit des lignes de commande, transmettez le mode choisi comme une valeur complète plutôt que de concaténer du texte non validé. N'acceptez que profile, real et advanced, et rejetez toute autre valeur avant de démarrer le navigateur. Un lancement qui échoue est plus facile à diagnostiquer qu'une session qui utilise silencieusement une autre politique d'affichage.

Valider et consigner une politique

1. Démarrez une session avec le profil choisi et un mode de DPR.
2. Gardez la fenêtre, l'écran et le DPR inchangés pendant toute la vérification.
3. Démarrez une seconde session avec le même profil et le même mode et vérifiez que le comportement d'affichage concorde.
4. Pour comparer des modes, ne modifiez que --bot-dpr et consignez la commande de lancement complète de chaque exécution.

Vérifier l'empreinte de votre navigateur présente des outils de vérification publics qui montrent les valeurs d'affichage annoncées.

Situation	Action
Le comportement d'affichage du profil est attendu	--bot-dpr=profile
La session doit suivre l'affichage de l'hôte	--bot-dpr=real
Un flux existant a besoin d'ajustements de mise en page	Évaluez l'option expérimentale --bot-dpr=advanced sur l'hôte visé, sinon gardez profile
L'affichage diffère entre les contextes	Définissez le mode avant que chaque contexte crée des pages ou des workers
Les dimensions avec interface suivent l'hôte	Ajoutez --bot-window=profile et --bot-screen=profile

L'entrée complète de l'option figure dans la référence des options de la CLI.

Tenez un court enregistrement pour chaque exécution. Les champs qui expliquent la plupart des écarts d'échelle d'affichage sont la version de BotBrowser, le profil, le mode de DPR, le viewport et la cible de capture, par exemple une capture d'écran, un PDF ou une mesure de page. Avec ces cinq champs, un relecteur peut dire si deux captures diffèrent à cause de la politique, du profil ou de la manière dont la sortie a été produite, sans rouvrir la page.

Pour comparer des modes sur une page, exécutez le même flux trois fois avec la même version du navigateur, le même profil, le même viewport, le même mode de fenêtre et le même mode d'écran, en ne changeant que --bot-dpr entre les exécutions. Conservez la commande de lancement à côté de chaque résultat. Si deux exécutions diffèrent, les commandes conservées montrent tout de suite si le mode était le seul changement ; si elles ne diffèrent pas, la page ne dépend pas de l'échelle d'affichage pour ce flux.

Les dimensions d'une capture d'écran sont exprimées en pixels CSS, alors que l'image de sortie peut être influencée par le facteur d'échelle de l'appareil. Un test qui compare des images doit garder le mode de DPR fixe pour la capture de référence comme pour la capture actuelle. Sinon, une mise en page peut rester inchangée alors que les dimensions de l'image ou le rendu du texte diffèrent.

Les flux PDF et d'impression ont leurs propres règles de taille de page, mais la mise en page web qui alimente l'impression dépend toujours des valeurs de viewport et d'affichage. Choisissez la politique de DPR avant de charger le document, puis gardez les réglages d'impression séparés des réglages d'affichage. Il devient ainsi plus facile de distinguer un changement de mise en page CSS d'un changement de format de papier.

Pour la régression visuelle, stockez la politique à côté du viewport et de la version du navigateur dans les métadonnées du test. Régénérez une référence uniquement lorsque la politique d'affichage prévue change. Ne mettez pas à jour les captures simplement parce qu'un exécuteur a un autre moniteur. Utilisez profile pour des références portables ou real pour des tests explicitement liés à un poste de travail.

Avant de livrer une configuration, vérifiez les points suivants dans l'enregistrement de lancement :

• la version de BotBrowser est fixée ;
• la cible du profil et le rôle de l'hôte sont documentés ;
• le mode de DPR est explicite ;
• les modes de fenêtre et d'écran sont explicites ;
• le mode est défini avant la création de la première page ;
• les tests de captures ou de mise en page adaptative utilisent la même politique que leur référence ;
• chaque configuration par contexte consigne sa propre politique d'affichage ;
• le passage de profile à real ou advanced est examiné comme un changement de comportement.

Ces vérifications n'exigent pas qu'une page expose des données privées du profil. Elles rendent claire l'origine du comportement d'affichage pour l'équipe qui exploite le navigateur. Si une mise en page diffère après un déploiement, l'enregistrement de lancement vous donne les premiers points de comparaison.

Déployer et maintenir une politique

Commencez par un profil représentatif et un flux applicatif. Exécutez le flux avec profile, puis répétez-le avec la même version du navigateur, le même viewport et les mêmes réglages de fenêtre. Si l'affichage de l'hôte fait partie de l'exigence, répétez la comparaison avec real. Conservez la sortie de chaque exécution avec l'enregistrement de lancement. L'équipe dispose ainsi d'un petit jeu de référence avant d'appliquer la politique à un groupe plus large.

Déployez d'abord le mode choisi sur un groupe de contextes. Vérifiez les pages qui utilisent une navigation adaptative, la sélection d'images, des tableaux, des graphiques et des mises en page d'impression, car ces zones montrent souvent les changements d'affichage plus tôt que les pages de texte ordinaires. Si le résultat convient, appliquez la même configuration aux autres contextes qui représentent la même famille d'appareils.

Traitez le mode choisi comme une partie de l'entrée du test, pas comme un détail d'environnement. Lorsqu'un rapport de bogue indique qu'une page avait un aspect différent, la première question est de savoir quelle source d'affichage la session utilisait. Si l'enregistrement de lancement répond à cette question, l'enquête peut passer directement à la page, au profil ou à l'hôte.

Ne mélangez pas les changements de politique avec un changement de version du navigateur, une migration de profil ou une refonte du viewport. Chacun de ces changements peut modifier le comportement de la mise en page. Lorsque plusieurs changements sont nécessaires, appliquez-les dans des exécutions de test séparées et gardez les enregistrements séparés. Une séquence claire permet d'identifier quel changement a influencé le résultat.

Après le passage à une nouvelle version de BotBrowser, réexaminez la politique choisie même si la ligne de commande n'a pas changé. La valeur par défaut reste profile, mais une version peut modifier la documentation disponible ou les options prises en charge. Réutilisez le même profil et les mêmes réglages de capture pour une comparaison avant et après. Si le résultat change, vérifiez dans cet ordre la version du navigateur, le profil, le mode de fenêtre, le mode d'écran et le mode de DPR.

Stockez la version du navigateur, le profil, le mode choisi, le viewport et la cible de capture à côté de la configuration du test ou du service. Cet enregistrement est utile lorsqu'une page modifie sa mise en page adaptative, lorsqu'une source d'image change ou lorsqu'une capture est produite à une taille inattendue. Il donne aussi aux relecteurs une liste concrète de valeurs à approuver avant un déploiement.

Les réglages d'affichage de l'hôte peuvent influencer la taille du texte, le contraste et le comportement de saisie sur un poste de travail avec interface. Si un opérateur utilise directement le navigateur, real peut correspondre aux attentes d'affichage de cette personne. Si le navigateur est une session portable basée sur un profil, profile garde le comportement d'affichage stable lorsque l'hôte change. Discutez de ce choix avec les personnes qui utilisent la session au lieu de choisir un mode uniquement d'après les valeurs par défaut du serveur, et menez les revues d'accessibilité avec le même viewport et les mêmes réglages de fenêtre qu'en production.

Les erreurs les plus fréquentes sont de laisser le mode implicite alors que la machine hôte change, de modifier le DPR après qu'un contexte a déjà créé des pages et d'utiliser advanced comme un réglage général de qualité. Écrivez explicitement les trois politiques d'affichage lorsqu'un flux en dépend, créez un nouveau contexte pour une nouvelle politique d'affichage et limitez advanced au flux qui en a besoin.

Une politique d'affichage est plus facile à maintenir lorsqu'elle est visible à côté du reste de la configuration de lancement. Indiquez le mode choisi dans les notes de déploiement, les jeux de test et les procédures d'exploitation, afin qu'un collègue puisse savoir si une session suit le profil ou l'hôte sans ouvrir la page. Lorsqu'une configuration passe du développement à la production, conservez le mode et les réglages de fenêtre et d'écran associés, et consignez l'ancien et le nouveau mode avec les références visuelles mises à jour chaque fois qu'un déploiement le change.

BotBrowser fournit l'option --bot-dpr pour choisir la politique de ratio de pixels de l'appareil (profile par défaut, real pour l'affichage de l'hôte et advanced, expérimental). Définie avant qu'un contexte crée sa première page, elle permet aux sessions de bureau et par contexte de garder une seule source d'échelle documentée, de sorte qu'une équipe peut comparer des exécutions en ne changeant que cette option. BotBrowser ne peut pas faire en sorte que advanced remette à l'échelle toute la page et ne garantit pas des mesures de mise en page ou des captures identiques ; il ne contrôle pas le moniteur de l'hôte, le CSS adaptatif de la page ni l'usage que fait un site de la valeur annoncée.

Pour un changement de ratio qui arrive sans redimensionnement, voir le guide des événements de viewport mobile.

Sources publiques

• MDN : Window.devicePixelRatio
• Documentation BotBrowser : politique de ratio de pixels
• Options de la CLI BotBrowser : --bot-dpr

Conclusion pratique

Traitez --bot-dpr comme une entrée de test : choisissez profile pour des références portables, real seulement lorsque le moniteur du poste de travail est l'exigence, et évaluez advanced sur l'hôte prévu au lieu de l'adopter par défaut. Gardez ensuite un enregistrement de lancement par exécution avec la version de BotBrowser, le profil, le mode, la fenêtre d'affichage et la cible de capture, afin qu'un écart de capture ou de mise en page responsif désigne la page plutôt qu'un réglage d'affichage non consigné.