Headless vs. GUI¶
Some systems don't have a display attached, so we can run the browser in headless mode to enable our browser-based studies.
The Automator can actually run in three ways:
- Simulated headless mode
- GUI mode
- Chrome-native headless mode
If you are unsure which one to use, or if you can only connect to the operating system via SSH, use the simulated or Chrome-native headless version.
You can also directly call the binary (surfmeter-automator.cjs) with node, but it is recommended to use any of the two wrappers (headless or GUI).
Here is a table that explains the differences:
| Mode | Description | Linux (with a GUI) | Linux (SSH/CLI/Docker) | macOS |
|---|---|---|---|---|
| Simulated headless | Runs the browser in a virtual X display on display :123 |
✔️ | ✔️ | ❌ |
| GUI | Runs the browser in the current GUI, in a new window | ✔️ | ❌ | ✔️ |
| Chrome-native headless | Runs the browser in headless mode | ✔️ | ✔️ | ✔️ |
Simulated Headless Mode¶
To run the simulated headless version, run:
This is for installations without an attached display, or where the OS does not have an X Server running already. It is also the default mode that we recommend for Docker-based execution.
In this headless mode, Automator will create and run an X display on display number :123, so you will not see a browser window while the tests are running. If an X display already exists at this port, it will render the browser on that display. If no display exists, it will create one temporarily and shut it down immediately after Automator exits.
You can set up a permanent display instance via X Window Server Daemon via xvfb which allows you to, e.g., connect a VNC instance to it. This is already the case for our Docker images.
Changing the Resolution¶
The default display resolution is 1920x1080.
You can change this resolution by specifying the HEADLESS_RESOLUTION environment variable in the format <width>x<height>x<bitdepth>, e.g.:
Warning
Changing this resolution on demand is not possible when you use the xvfb daemon. If you want to permanently change its resolution, you have to change the resolution in the xvfb-surfmeter.service file instead. See the next section for details.
If you want an ad-hoc test with a different resolution, you can choose a different display number for the temporary Xvfb instance, by specifying the SURFMETER_DISPLAY environment variable. For example:
Optional: X Window Server Daemon via xvfb¶
Having a temporary display may make troubleshooting the measurements more difficult in case a VNC connection is needed. If you want a permanent display instance to be available, you can create a systemd script that starts an Xvfb daemon. This will make the display :123 permanently available.
The instructions for creating the systemd script are printed at the end of the setup.sh script, but the xvfb-surfmeter.service file is also easy to create manually.
Simply write this content:
[Unit]
Description=Start Xvfb service for Surfmeter Automator
After=
Wants=
[Service]
Restart=always
Type=simple
ExecStart=Xvfb :123 -screen 0 1920x1080x24
Environment=
[Install]
WantedBy=multi-user.target
to the file $HOME/.config/systemd/user/xvfb-surfmeter.service, where $HOME is the home directory of the user that will run the Automator.
Warning
We recommend not running this as root. Instead, create a user for the Automator and run it as that user.
Note that the default resolution for the systemd service is the same as in our surfmeter-automator-headless script: 1920x1080x24. You may choose a different resolution by simply modifying the contents of the systemd configuration file and replacing that default resolution.
You can ensure that the service is running via:
systemctl --user daemon-reload
systemctl --user start xvfb-surfmeter.service
systemctl --user enable xvfb-surfmeter.service
systemctl --user status xvfb-surfmeter.service
Check the file $HOME/.config/systemd/user/xvfb-surfmeter.service for the systemd configuration that it installs.
To remove the systemd service, simply remove the file:
systemctl --user stop xvfb-surfmeter.service
systemctl --user disable xvfb-surfmeter.service
rm $HOME/.config/systemd/user/xvfb-surfmeter.service
systemctl --user daemon-reload
Observing the Simulated Headless Mode¶
You will not see what the browser is doing, and cannot interact with it, unless you run a VNC server on the same machine.
Please ensure that no other process is running on that display so that you don't get any unwanted overlays.
GUI Mode¶
To run the GUI version, run:
This is for installations with an attached display or where the OS has an X Server running already that is visible to the user. You will see what the browser is doing, and can interact with it (although you have to be quick, since everything is automated).
Chrome-native Headless Mode¶
To run the Chrome-native headless mode, run:
where <command> is any of the commands listed in the commands and options section.
This is for installations without an attached display, or where the OS does not have an X Server running already. In this headless mode, Automator will use the Chrome-native headless mode with the --headless=new flag. You will not see what the browser is doing, and cannot interact with it.
Warning
For most purposes, this should work just as well as the simulated headless mode. However, it is not as well tested as the simulated headless mode, and may not work for all video tests.
Note that you would have to append this option to all commands you run, and that you cannot use the surfmeter-automator-headless or surfmeter-automator-gui wrappers. We recommend adding this option to the automatorConfig.json file as a cmdSuffix option, so that you don't have to type it every time.