Dependencies

• An overview of automated testing in the Metaplay SDK - You should have an idea of how automated testing works across the Metaplay SDK as described in Introduction to Automated Testing.
• .NET unit testing in the Metaplay SDK - You should first familiarize yourself with how to do .NET Unit Testing with Metaplay.
• Dashboard testing - If you want to target the dashboard with tests, you should familiarize yourself with the basics of LiveOps Dashboard Testing first.
• Working proficiency with Playwright.NET - If you want to write tests targeting the LiveOps Dashboard, you should familiarize yourself with the Playwright for .NET.

Overview

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.

Intended Use Cases

The following are good use cases for the system tests:

• Testing the server HTTP endpoints. By adding a reference to your game's Server C# project, you have access to the return types used by the HTTP endpoints, to avoid duplicating the types in the tests.
• Using simulated clients to connect to the server. For now, the capabilities for simulated connections are relatively limited and will be expanded on in the future to allow scripted execution of player actions and such.
• Test cases that also need to operate the LiveOps Dashboard in addition to the other use cases.

While this testing method can cover a lot of ground, you should prefer simpler testing methods when possible:

• For pure dashboard tests, it's usually better to follow the dedicated tools at LiveOps Dashboard Testing.
• For testing needs where the game server does not need to be running, take a look at .NET Unit Testing for a simpler approach.

Adding Game-Specific Tests

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.

Scaffold the Test Project

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)
├── ...

Running the Tests

Prerequisites

Install Playwright CLI on your machine:

$ dotnet tool install --global Microsoft.Playwright.CLI
$ playwright install

Running Locally

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:

1. Start the game server (other ways of running the server are also fine):

   Backend/Server$ dotnet run

2. 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

3. 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.

Additional Run Options

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

Writing Tests

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:

• The TestUtil class provides some helpers for writing tests.
• The MetaPageTest class is a handy replacement for Playwright's MetaPageTest with some additional built-in features.

Helper Functionality

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.

Invoking HTTP Endpoints

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.

Testing the LiveOps Dashboard

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:

• Video capture from test runs is taken if run with the environment variable CAPTURE_VIDEO=1.
• Screenshots of the browser window are taken on failure, assuming that the browser was used to navigate to a page.

The output files are written to the PlaywrightOutput/ directory by default.

Simulated Clients

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.

Further Reading

Now, you should have the knowledge to write more complex system tests with Metaplay. To deepen your understanding, check out the following guides:

• Unit testing C# with NUnit and .NET Core - Helps you better understand how to use NUnit for writing .NET tests.
• Playwright.NET Test Writing Guide - To better understand how to use Playwright.NET to write tests targeting the LiveOps Dashboard.
• Integration Testing - To understand how to run all tests in your CI system when using the Metaplay integration test runner.