Appearance
Appearance
Metaplay system tests are used to test your game's backend from the outside. System tests are suitable for invoking various HTTP endpoints from the outside, for using simulated clients that connect to the game server over the network, as well as interacting with the LiveOps Dashboard.
The system tests utilize Playwright.NET which is a powerful testing framework that also allows controlling a virtual browser as part of the tests. Playwright.NET itself extends NUnit with the browser functionality.
The following are good use cases for the system tests:
Server
C# project, you have access to the return types used by the HTTP endpoints, to avoid duplicating the types in the tests.While this testing method can cover a lot of ground, you should prefer simpler testing methods when possible:
The project scaffolding does not include system tests by default so you need to add them first. It's easiest to do by copying these from the Idler sample in the SDK release package. Follow the steps below.
First, copy the test project from MetaplaySamples/Idler/Backend/System.Tests
into your game project in the directory Backend/System.Tests/
.
Special directory naming
The system tests must be located in the Backend/System.Tests/
directory of the game project for the integration tests to be able to detect their presence. The integration tests will then orchestrate an environment where the game server, including the LiveOps Dashboard, is started in a background process.
Optionally, add the newly copied C# project into your IDE project, for example, the Visual Studio solution file at Backend/MyGame-Server.sln
.
Backend The game-specific backend directory
├── System.Tests Playwright.NET test project
├── MyProject-Server.sln Solution file for the backend (optional)
├── ...
Install Playwright CLI on your machine:
$ dotnet tool install --global Microsoft.Playwright.CLI
$ playwright install
The Playwright.NET tests are run similarly to .NET unit tests with the exception that the game server and LiveOps Dashboard must be running as the tests will try to contact it.
To run the tests on your local machine, follow these steps:
Start the game server (other ways of running the server are also fine):
Backend/Server$ dotnet run
If you have scaffolded a game-specific dashboard, start it in development mode. Otherwise, you can skip this step.
Backend/Dashboard$ pnpm install
Backend/Dashboard$ pnpm dev
Run the test project:
Backend/System.Tests$ dotnet test
...
Starting test execution, please wait...
A total of 1 test files matched the specified pattern.
Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: 1 s - System.Tests.dll (net8.0)
Alternatively, many IDEs have integrated tools for running the tests. For example, Visual Studio has Test Explorer window.
By default, the tests run using a headless browser. If you want to see what the browser is doing during the tests, run with the environment variable HEADED=1
:
# On Windows:
set HEADED=1
Backend/System.Tests$ dotnet test
# On Linux and Mac:
Backend/System.Tests$ HEADED=1 dotnet test
To record video from test runs, set the environment variable CAPTURE_VIDEO=1
when running:
# On Windows command prompt:
Backend/System.Tests$ set CAPTURE_VIDEO=1
Backend/System.Tests$ dotnet test
# On Linux/Mac:
Backend/System.Tests$ CAPTURE_VIDEO=1 dotnet test
The tests are written as NUnit test cases as with .NET Unit Testing. There are some key differences, though, explained in more details in the sections below:
TestUtil
class provides some helpers for writing tests.MetaPageTest
class is a handy replacement for Playwright's MetaPageTest
with some additional built-in features.The TestUtil
class contains various utilities that can be helpful when you are writing tests:
TestUtil.ServerBaseUrl
has the base URL to access the game server. This is used to access the HTTP endpoints exposed by the game server.TestUtil.DashboardBaseUrl
has the base URL to the LiveOps Dashboard. This is used when using the browser to test the dashboard features.TestUtil.HelloResponse
contains the response from the game server's /api/hello
endpoint. It contains information about the project's configuration and features enabled. These can be useful in making conditional tests for example for features that don't exist in all environments.Below is a simple test that accesses a webhook HTTP endpoint on the game server:
[Test]
public void WebhookTests()
{
// Resolve the URL on the game server using TestUtil.ServerBaseUrl.
string url = $"{TestUtil.ServerBaseUrl}/webhook/test";
// Make the request with MetaHttpClient.
MetaHttpResponse response = await MetaHttpClient.DefaultInstance.GetAsync(url);
// Check the result.
Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
}
You should use strongly-typed return values for your HTTP endpoints to help with testing. The types from the game server project can be used directly in the tests to avoid needing to write copies of them in the test project. This also helps remember to update the tests whenever changing the endpoint return types.
You can write tests against the dashboard with Metaplay's system tests by using Playwright for .NET. Playwright can be used normally but Metaplay provides a few extra helpers to capture screenshots and videos from the tests.
Below is a simple test case that utilizes Playwright.NET to use a virtual browser to access the game's LiveOps Dashboard.
// Use Metaplay's MetaPageTest instead of Playwright's own PageTest for some
// extra functionality. See below for details.
[TestFixture]
public class MyBrowserTests : MetaPageTest
{
// Simple test case to navigate to the game's dashboard and check the title
// using Playwright.NET's browser functionality.
[Test]
public void TestPlayerPageTitle()
{
// Navigate the browser to the dashboard's /players page.
Page.GotoAsync($"{TestUtil.DashboardBaseUrl}/players");
// Check that the title is what we expect it to be.
Expect(Page).ToHaveTitleAsync("LiveOps Dashboard - Manage Players");
}
}
The MetaPageTest
base class that this test texture inherits is a drop-in replacement for Playwright's PageTest
class, but adds some extra functionality:
CAPTURE_VIDEO=1
.The output files are written to the PlaywrightOutput/
directory by default.
Work in progress
Another intended use case for the system tests is to write tests that simulate client connections to the game server. However, this area is still in active development, and the current facilities for this are very limited. Please contact us if you want to start writing tests that use simulated clients.
Now, you should have the knowledge to write more complex system tests with Metaplay. To deepen your understanding, check out the following guides: