Support emulation of viewport width and height

[OrKoN]

For Puppeteer, we need an ability to control the viewport. We need at least the ability to specify the width, height in CSS pixels and deviceScaleFactor.

1. https://source.chromium.org/chromium/chromium/src/+/refs/heads/main:third_party/blink/renderer/core/inspector/dev_tools_emulator.cc;l=342;drc=a61b95c63b0b75c1cfe872d9c8cdf927c226046e
2. https://source.chromium.org/chromium/chromium/src/+/refs/heads/main:third_party/blink/renderer/core/frame/screen_metrics_emulator.cc;l=61;drc=047c7dc4ee1ce908d7fea38ca063fa2f80f92c77

Other kinds of emulation can be considered separately.

[OrKoN]

cc @sadym-chromium @foolip

[whimboo]

In CDP this is handled via the Emulation.setDeviceMetricsOverride command.

I assume we also most likely want an emulation module for BiDi. @jgraham what do you think?

[jgraham]

A question I have is what the scope of the overrides is. Is it per Target in CDP? Or for the entire browser? In the former case should it be per top-level browsing context in BiDi?

[sadym-chromium]

A question I have is what the scope of the overrides is. Is it per Target in CDP? Or for the entire browser? In the former case should it be per top-level browsing context in BiDi?

Correct, in case of Chromium it's per target. So top-level browsing context would be perfect.

[whimboo]

Some additional things that would need discussion:

• How to detect if device emulation is supported and when to raise an "unsupported operation" error?
• Using a capability as returned from New Session to indicate if it is available?

[OrKoN]

I think something like this would work:

emulation.setViewport({
  context: "",
  width?: ddd,
  height?: ddd,
  devicePixelRatio?: d,
}?)

Undefined values reset the emulation to the original state. I think this should apply to the top-level context and all sub-contexts: 1) width/height applies only to subcontexts that have a concept of the viewport 2) devicePixelRatio applies to all subcontexts with visual components. We could start with the main component only but I think it is how it should be used. We also need smth to perhaps configure emulation for the new contexts. Not sure what would be the best way here.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Support emulation of device metrics (width, height, deviceScaleFactor, ...).

The full IRC log of that discussion

<jgraham_> Topic: Support emulation of device metrics (width, height, deviceScaleFactor, ...)
<orkon> q+
<jgraham_> github: https://github.com//issues/415
<jgraham_> ack orkon
<jgraham_> orkon: A good starting point would be the ability to change the viewport and the device pixel ratio.
<jgraham_> orkon: Width/height and dpr for a given context, which should apply to all sub contexts.
<jgraham_> q+
<jgraham_> ack jgraham_
<jgraham_> jgraham: Use case is mobile-ish testing on desktop?
<patrickangle_> q+
<JimEvans> q+
<jgraham_> orkon: It's mostly about responsive design at this stage, but we could extend it to mobile in the future. It's important for screenshots and testing that elements are in the right places.
<jgraham_> ack patrickangle_
<jgraham_> patrickangle_: I get the pixel ratio emulation. I'm having difficulty understanding why the width/height is needed instead of resizing the window.
<jgraham_> orkon: For mobile emulation you probably need more e.g. portrait/landscape and device scale(?), so it's partially related to mobile enulation, but it's a subset
<jgraham_> patrickangle_: We want it to be very well specified what happens when you set the viewport. Different people have different expectations. In Safari RDM, we don't adjust the screen size because ideally that's not what people are using to test against, even for mobile devices that might not be the actual device screen size.
<jgraham_> orkon: This isn't directly about the window size. In Chrome currently you can set the viewport size. Affects window.innerWidth and innerHeight.
<jgraham_> orkon: From what I understand it's like a screen size for the content area, but I"m not sure of the details.
<jgraham_> whimboo: Difference between resizing the window and the viewport is that you can set it just for a single tab in the window.
<jgraham_> orkon: It doesn't count the browser UI so it's clearer
<jgraham_> ack JimEvans
<JimEvans> q-
<jgraham_> jgraham: Are you thinking it would apply just to top level tabs and descendents or all contexts?
<JimEvans> I abdicate my place. I misunderstood the full context.
<jgraham_> orkon: It should apply to frames. If the main tab has multiple frametrees, maybe they should all use the same dimensions.
<jgraham_> jgraham: So basically a per-tab setting?
<jgraham_> orkon: Pretty much.
<jgraham_> q?
<whimboo> q+
<jgraham_> ack whimboo
<jgraham_> whimboo: Should it be possible to set this globally so that it inherits into new tabs, or should you have to call it explicitly for each tab?
<jgraham_> orkon: I think we might want both options. You can't currently intercept creation of a new context, so maybe the context could be optional. But a specific context seems like it would work for most use cases. So maybe it doesn't have to be enabled from the beginning
<jgraham_> whimboo: You need to make sure that layout has been updated after setting the overrides before continuing with other commands
<jgraham_> jgraham: Are you planning to write spec text for this?
<jgraham_> orkon: Yes; I may need some help

[ewinslow]

#415 (comment)

I get the pixel ratio emulation. I'm having difficulty understanding why the width/height is needed instead of resizing the window.

I just wanted to chime in here to confirm that in my experience the viewport size is much more relevant than browser window size. We have many tests where having consistent dimensions for the viewport over time is important (screenshots). As it is today, every browser has its own amount of custom UI around the viewport and this frequently changes slightly (1-3px) between versions of the same browser which is all that is needed to trigger failures in diff tests. We built a custom tool that takes a viewport size and resizes the browser window to achieve the requested viewport size, but it tends to be a bit flaky on some browsers and fails for small enough dimensions.

A standard protocol for configuring viewport size would be welcome.

[whimboo]

The work is happening on #425

[OrKoN]

#425 handles the viewport, DPR will be considered separately.