Published 2023.01

As of the 2023.02 release of GameDriver, you are able to test WebGL applications both in the Unity editor or deployed to a browser. The connection paths are reversed from the standard GameDriver Agent and ApiClient, and there are other considerations such as how to launch the browser for testing. This article will cover the main points of the configuration and any other differences to note.


  • GameDriver 2023.02 or higher
  • Unity Input System version 1.3.0 or higher


The GDIOAgent now includes additional options for connecting via Web Sockets. This should be disabled when testing via the editor and enabled when deploying to a standalone WebGL build. The Web Sockets URL option is used to define where the test will be executed and defaults to ws://localhost:7072. This can be overridden in the launch command for the app. See the same code in "Configuring the Test" below for more information.

Note: When using GameDriver 2023.06 or older, the Unity project should include the GDIO_UNITY_NEW_INPUT_IL2CPP scripting define symbols to enable GameDriver to work with the Input System package.

Configuring the Test

Since we will be running our tests against the app running in a browser, we'll use Selenium to launch and control the browse in an automated manner, rather than launch the browser automatically. There are numerous articles available for working with Selenium if you are unfamiliar. For the purpose of these tests, we only need to include the Selenium package in our test class and leverage a few basic commands.

First, add the Selenium package to your project. In Visual Studio, we will use the Nuget Package Manager for this.

For these instructions, we're using the Selenium.WebDriver package, as well as the latest Selenium.WebDriver.ChromeDriver which is responsible for the browser itself. You can use whatever browser driver is necessary for your testing.

We then add the following lines to our GameDriver Test. If you have not yet configured a basic GameDriver test, please see the Getting Started article first.

using System;
using NUnit.Framework;
using gdio.common.objects;
using gdio.unity_api.v2;
using gdio.unity_api;
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;
using System.Threading.Tasks;

The OpenQA.* libraries are used for controlling the web browser using Selenium, while the System.Threading.Tasks library is used for starting the test before launching the application, as we will cover below.

Next, we need to define the Selenium WebDriver, alongside the GameDriver ApiClient. This is done in the Class scope so we may refer to it throughout the test.

public class MyClass
    ApiClient api;
    IWebDriver driver;

Then, within the [OneTimeSetUp] directive (or equivalent if you are not using NUnit), we will launch the browser, start the test Client, and then launch the application in the browser. Unlike standard GameDriver tests, the WebGLClient acts as the server endpoint in this scenario, since a browser cannot provide an endpoint.

public void Connect()
    // initialize the ApiClient
    api = new ApiClient();

    // initialize the browser and give it time to load
    driver = new ChromeDriver();

    // Start the test server (this test) as a Task
    var task = new Task(() => api.UseWebSockets(testHost, 7072, true, 120));
    // Launch the WebGL application in the ChromeDriver browser using the default port
    // Optional argument to specify the return path, i.e. http://localhost/?GDIOServer=localhost&GDIOPort=7072);
    driver.Url = ("http://localhost/~user/WebGLDemo/");

    // Give the application plenty of time to load. Should not exceed the timeout value of WebGLClient above.

You will notice we're giving the WebGLClient 120 seconds to wait, and then adding 30 seconds of Wait time to the end of this block. This is due to the amount of time it can take to load the WebGL applications. Be sure to test how long yours takes to load, and adjust these settings accordingly.

Running Tests

Theoretically, tests should run the same in a WebGL build as they would in another target or even the editor. However, due to the performance limitations of web browsers, some adjustments may be required. For example, a trick that is often used in GameDriver tests to provide input for a given number of seconds is to query the current frames per second (FPS) of the running application and use that figure as the input for the number of frames for a given action, such as:

// Press S for ~3 seconds
api.KeyPress(new KeyCode[] { KeyCode.S }, (ulong)api.GetLastFPS() * 3);

In WebGL builds this approach may be unreliable. Therefore you will need to input the specific number of frames used for input.

// Press S for 300 frames
api.KeyPress(new KeyCode[] { KeyCode.S }, 300);

Additional Information

  • The legacy Input Manager is not supported at the time of this writing but may be supported in the future.
  • To view the logs of a WebGL application, use the Developer Tools > Console in most modern browsers.
  • For information on how to set up a local web server on macOS, see this article and this article.
  • For a quick start guide on how to use Selenium, see this article.
  • For additional information on configuring your web server for Unity WebGL builds, see this article and this article.

If you experience issues not covered in this guide, please email or visit our GameDriver-Users Slack workspace.