Chromium UI Platform

Multi-Screen Testing in Chromium

Chromium supports testing multi-screen environments under interactive_ui_tests on most desktop platforms through the VirtualDisplayUtil (ui/display/test/virtual_display_util.h) interface. This interface instantiates virtual displays at the operating system level to simulate a multi-display environment being presented to Chromium. For more information on the background and design, see “Virtual Displays For Automated Tests”.

How to use

Simply invoke display::test::VirtualDisplayUtil::TryCreate to create an instance of VirtualDisplayUtil. The function will return nullptr on platforms that are unsupported, or not implemented. Tests should generally skip (GTEST_SKIP()) when this function returns nullptr.

Supported Platforms

Mac, Linux (X11), and Windows are supported.

ChromeOS mutli-screen testing is supported via display::test::DisplayManagerTestApi and does not yet have a VirtualDisplayUtil implementation.

Special Considerations

MacOS

Requires macOS version 11.0+. The implementation relies on undocumented CoreGraphics APIs and risks breakage at any time. There is an open request for official API support.

Windows

On Windows, administrative access is required for the utility to function. You must run the chrome/test binary with elevated privileges.

Windows hosts must have a special driver installed for the utility to work. The driver and controller source code is located at //third_party/win_virtual_display. The pre-built driver is available in CIPD at the path chromium/third_party/win_virtual_display/windows-amd64. Developers may download the CIPD package and manually install the driver for local development:

  1. On the CIPD page: Pick the latest instance.
  2. Click Download and extract the zip file somewhere (i.e. C:\virtual-display-driver)
  3. Install the certificates and driver. Open PowerShell as Administrator and run the following 3 commands:
Import-Certificate -FilePath C:\virtual-display-driver\ChromiumVirtualDisplayDriver.cer -CertStoreLocation Cert:\LocalMachine\AuthRoot
Import-Certificate -FilePath C:\virtual-display-driver\ChromiumVirtualDisplayDriver.cer -CertStoreLocation Cert:\LocalMachine\TrustedPublisher
pnputil.exe /add-driver C:\virtual-display-driver\ChromiumVirtualDisplayDriver.inf /install

Linux (X11)

Linux requires an X11 environment that supports virtual outputs in XrandR. It is highly recommended to use //testing/xvfb.py to set up a virtual X server that supports the utility. For example, the following command will run tests under a virtual X server environment that works with the utility:

python3 testing/xvfb.py --use-xorg $(pwd)/out/current_link/interactive_ui_tests --gtest_filter=*VirtualDisplayUtil*

Running outside of xvfb.py directly on the host X server should work, but is not explicitly documented here. The host must have xserver-xorg-core, xserver-xorg-video-dummy and x11-xserver-utils packages installed. See //testing/xvfb.py for more details on the required Xorg/XRandR setup.