Display Modes

Most probes do not have a display, but browser-based studies need one. The --display option sets how the browser gets it. You normally do not need to change the default, auto.

• auto: use the virtual display at SURFMETER_DISPLAY (default: :123) if it is running. Otherwise, start one for the run.
• xvfb: always start a new virtual display for the run.
• browser-headless: use Chrome's headless mode without a display.
• :N: use an existing display with the number N, for example a desktop session.

The environment variable DISPLAY is ignored unless you pass it explicitly. Each result records the mode that was used, in the diagnostics.display field of the report.

Permanent Virtual Display

The setup script installs the service xvfb-surfmeter.service, which keeps a virtual display running at :123. This lets you connect with VNC at any time. In Docker, set SURFMETER_PERSISTENT_DISPLAY=1 or SURFMETER_ENABLE_VNC=1 for the same result.

To check the service, run:

systemctl --user status xvfb-surfmeter.service

Studies also work without this service, since they then start a virtual display of their own.

Changing the Resolution

The default resolution is 1920x1080x24, which can stop some videos from playing in a higher resolution such as 4K. Set the resolution with the environment variable SURFMETER_DISPLAY_RESOLUTION, in the format <width>x<height>x<bitDepth>.

For one run:

SURFMETER_DISPLAY_RESOLUTION=3840x2160x24 surfmeter study start --studyId STUDY_YOUTUBE

For a schedule, set it in the env section of the schedule config, globally or for one entry:

{
  "id": "youtube-4k",
  "studyId": "STUDY_YOUTUBE",
  "schedule": "5 * * * *",
  "env": {
    "SURFMETER_DISPLAY_RESOLUTION": "3840x2160x24"
  }
}

An existing display keeps its resolution

Setting SURFMETER_DISPLAY_RESOLUTION for a run only affects a display that Automator starts for that run. If xvfb-surfmeter.service is running, also use --display xvfb to start a separate display.

To change the permanent display's resolution, edit ~/.config/systemd/user/xvfb-surfmeter.service, then run systemctl --user daemon-reload and systemctl --user restart xvfb-surfmeter.service.

In Docker, set SURFMETER_DISPLAY_RESOLUTION in the environment of the container, and restart it.

Running on a Desktop Session

On a machine with a desktop, you can run the browser in your session, and watch what it does:

surfmeter study start --studyId STUDY_YOUTUBE --display $DISPLAY

Chrome's Headless Mode

Use --display browser-headless to run without any display. To use it for all scheduled studies, set the option in the schedule config:

{
  "globalScheduleSettings": {
    "options": {
      "display": "browser-headless"
    }
  }
}

Headless mode limits video testing and recording

This mode works for all network and web tests, but it is not as well tested for video. Screen recording does not work in this mode.