Dependencies

• Working knowledge with dashboard testing - You should be able to run and create Playwright tests for your custom dashboard as described in LiveOps Dashboard Testing.

Overview

Writing fast and stable tests can be complicated, so we have compiled some of our internal learnings into this page.

The Metaplay SDK has over a hundred built-in Playwright tests that cover most of the patterns you are likely to need for your game-specific tests. In addition to learning from this page, feel free to use our internal tests as a starting point for your own tests. You can find them in the MetaplaySDK/Frontend/DashboardPlaywrightTests folder.

Running Playwright Tests

When developing Playwright tests, you have several options for running them, each offering unique advantages for debugging and iteration. This section will guide you through the primary methods, including using the Command Line Interface (CLI) and the Visual Studio Code (VSC) plugin.

At Metaplay, we regularly use the CLI to run tests as a quick batch, while the VSC plugin is useful for debugging and running tests individually. We recommend using both methods to get the most out of your testing workflow.

Using the Command Line Interface (CLI)

The CLI provides a straightforward way to run your Playwright tests. Once you've installed the Playwright browsers, you can run your tests using:

pnpm test-e2e

This command executes all end-to-end (e2e) tests in your project. For more advanced usage, such as running specific test files or configuring headless vs. UI mode, refer to the Playwright CLI documentation.

Using the Visual Studio Code (VSC) Plugin

For a more integrated development experience, the Playwright Test for VSCode plugin offers powerful features directly within VSC. Follow these steps to set it up:

1. Install the Plugin

   • Navigate to the Extensions view in VSC by clicking on the Extensions icon in the Activity Bar on the side of the window or by pressing Ctrl+Shift+X (Win) or Cmd+Shift+X (Mac).
   • Search for "Playwright Test for VSCode" and install the Playwright Test plugin by Microsoft.

   

2. Configure the Plugin

   • Open the Command Palette by pressing Ctrl+Shift+P (Win) or Cmd+Shift+P (Mac) and type "Test: Toggle Playwright Configs".
   • Choose the configuration file in your dashboard project. You can also add our core tests if you want. This controls what tests are displayed in the Test Explorer view.

3. Run Tests

   • With the plugin configured, you can run tests directly from the Test Explorer view in VSC. Click on the Test icon in the Activity Bar to open the Test Explorer.
   • Here, you can see all your tests organized by file. Click the play button next to any test or test suite to run it.

   

The VSC plugin also supports debugging tests, allowing you to set breakpoints and step through your test code. For detailed instructions on debugging, refer to the Playwright Test for VSCode documentation.

Writing Playwright Tests

Writing Playwright tests for the LiveOps Dashboard involves a mix of common patterns and custom actions. This section will guide you through the process of writing your own tests and the common best practices.

To create Playwright tests, add more testName.spec.ts files to your Dashboard/tests/e2e folder.

Example: Check That a Page Renders

The most common pattern in the LiveOps Dashboard is to check that a page renders correctly. This involves navigating to a page and checking that the main elements are visible. Let's look at an example from the playerDetails.spec.ts core test.

Step-by-Step Guide

1. Navigate to the Page:

   • Start by navigating to the player details page using the page.goto method.

2. Locate the Main Elements:

   • Use page.getByTestId to locate elements by their data-testid attribute. This is the most reliable way to maintain tests over time.

3. Assert Element Visibility:

   • Use Playwright's expect function to assert that the elements are visible and contain the expected text.

Example Code

Here's a complete example of a test that checks the rendering of the player details page:

import { test, expect } from '@metaplay/playwright-config';

test.describe('Player Details Rendering', () => {
  test.beforeEach(async ({ page, freshTestPlayer }) => {
    await page.goto(`/players/${freshTestPlayer}`);
  });

  test('Overview and admin tools cards', async ({ page, freshTestPlayer }) => {
    // Get the overview card.
    const overviewCard = page.getByTestId('player-overview-card');

    // Check that the overview card contains the player ID.
    await expect(overviewCard).toContainText(freshTestPlayer);

    // Get the admin actions card.
    const adminActionsCard = page.getByTestId('player-admin-actions-card');

    // Check that the admin actions card is rendered.
    await expect(adminActionsCard).toBeVisible();
  });
});

Adaptation Tips

• Custom Pages: Replace the URL and data-testid values with those relevant to your custom pages.
• Additional Elements: Add more expect statements to check the visibility of additional elements on the page.
• Conditional Checks: Use conditional logic to check for elements that may or may not be present based on feature flags or user roles.

Example: Performing Actions on a Modal and Checking the Result

Testing a feature by performing an action and checking the result is a common pattern in the LiveOps Dashboard. This involves interacting with a modal, performing an action, and then verifying the outcome. Let's look at an example from the editName.spec.ts core test.

Step-by-Step Guide

1. Navigate to the Page

   • Start by navigating to the page where the modal is accessible.

2. Open the Modal

   • Use page.getByTestId to locate the button that opens the modal and click it.

3. Perform the Action

   • Interact with the modal elements to perform the desired action.

4. Assert the Result

   • Use Playwright's expect function to assert that the result of the action is as expected.

Example Code

Here's a complete example of a test that edits a player's name using a modal and checks the result:

import { test, expect } from '@metaplay/playwright-config'

test.describe('Edit Player Name', () => {
  test.beforeEach(async ({ page, freshTestPlayer }) => {
    await page.goto(`/players/${freshTestPlayer}`)
  })

  test('Edits player name', async ({ page }) => {
    // Open the edit name modal.
    await page.getByTestId('action-edit-name-button').click()

    // Define the new name.
    const newName = 'Example Name'

    // Type the new name in the text input field.
    await page.getByTestId('name-input')
      .fill(newName)

    // Click the OK button to save the changes.
    // Please note the custom action `clickMButton` is used here.
    await clickMButton(page.getByTestId('action-edit-name-modal-ok-button'))

    // Check that the player overview card contains the new name.
    const overviewCard = page.getByTestId('player-overview-card')
    await expect(overviewCard).toContainText(newName)
  })
})

Adaptation Tips

• Custom Modals: Replace the data-testid values with those relevant to your custom modals.
• Additional Actions: Add more steps to perform additional actions within the modal. For example, asserting that the form validation works correctly with different inputs.
• Conditional Checks: Use conditional logic to handle different outcomes based on the action's behavior.

Fixtures In-depth

All Playwright tests in the LiveOps Dashboard use fixtures to set up the environment for each test. Fixtures are isolated between tests and can be used to provide context, pages, and other resources to the tests. Let's take a closer look at how fixtures work and how to use them in your tests.

Built-in Page Fixture

Consider the following sample test:

import { test, expect } from '@metaplay/playwright-config'

test('Trivial example', async ({ page }) => {
  await page.goto('https://example.com')
  const element = await page.getByTestId('example-element')
  await expect(element).toBeVisible()
});

The page fixture is a built-in fixture that acts like an individual tab in a browser. You can use this fixture to navigate to pages, interact with elements, and perform other browser actions. In this example, we first use the page.goto method to navigate to a URL and then use the page.getByTestId method to locate an element by its data-testid attribute.

Depending on the test, you may need additional fixtures to set up the environment. For example, you might need a fixture to create a new player before running the test.

Built-in Request Fixture

Consider the following sample test:

import { test, expect } from '@metaplay/playwright-config'

test('Request example', async ({ request }) => {
  const response = await request.get('https://example.com')
  const data = await response.json()
  await expect(data).toHaveProperty('exampleProperty')
});

The request fixture is a built-in fixture that allows you to make HTTP requests from your tests. You can use this fixture to interact with external APIs, fetch data, and perform other network-related actions. In this example, we use the request.get method to fetch data from an external API and then assert that the response contains a specific property.

You could use this to fetch data from your game server or other external services to set up the test environment or verify the test outcome.

Metaplay's freshTestPlayer Fixture

Metaplay provides several custom fixtures that you can use in your tests. These fixtures provide additional context and resources to your tests, making it easier to write and maintain them. The most useful custom fixture is freshTestPlayer, which provides a new player ID for each test.

import { test, expect } from '@metaplay/playwright-config'

test('Player-specific test', async ({ page, freshTestPlayer }) => {
  await page.goto(`/players/${freshTestPlayer}`)
  const element = await page.getByTestId('player-element')
  await expect(element).toBeVisible()
});

In this example, we use the freshTestPlayer fixture to get a new player ID for each test. We then navigate to the player details page using the player ID and assert that the player element is visible.

Notice how we can keep adding fixtures to the test function parameters as needed. This allows you to access multiple fixtures in a single test, and each fixture is isolated from any other test that may be running in parallel.

Common Best Practices

1. Test organizing

   • Follow the naming convention of featureName.spec.ts where the name should match with the component or view being tested.
   • Ideally, also match the folder structure of your custom components for easier discovery.
   • Use test.describe() to group related tests in a test suite.
   • Use test.beforeAll() and test.beforeEach() hooks to set up the page for your test suite. Usually, this involves navigating to a page and waiting until it has loaded.

2. Element selection

   • Use data-testid attributes in your components to make the right elements easy to discover. This is the most reliable way to maintain tests over time.
   • Use page.getByTestId() to select elements based on their data-testid attribute.
   • Avoid using CSS selectors or finding elements based on text content, as these can be brittle and break easily when the components change.
   • Use your browser's developer tools to inspect the elements and find the data-testid attributes in our built-in components. You can also check the source code, but just looking at the rendered page is usually faster.
   • Some of our complex components, like the MActionModalButton, have a specific pattern for data-testid attributes. You can find more information in the MActionModalButton documentation.

3. Parallelism

   • Playwright tests run in parallel by default, which can speed up your test suite significantly. You can control this via the Playwright config file.
   • Avoid writing tests that depend on a specific execution order, as they may not run in the order you expect.
   • Use our freshTestPlayer fixture to create a new player for each test, ensuring that tests are isolated from each other.
   • Be mindful of any background processes on the game server that may mutate the state of the game outside of the tests. This might include things like scheduled events starting or ending.

Debugging Playwright Tests

For a good workflow in writing and debugging Playwright tests, you should use the VSCode plugin. It provides a visual interface for running and debugging tests, making it easier to identify issues and iterate on them.

Trace Viewer

Playwright has a powerful feature called the trace viewer that allows you to visualize the execution of your tests. When you run a test, Playwright generates a trace.zip file that contains detailed information about the test run, including screenshots, console logs, and network requests.

In VSCode, you can automatically open the trace viewer by clicking the trace viewer button in the testing tab. This is the fastest way to debug test runs.

Alternatively, you can upload any trace.zip file to the Playwright trace viewer to view the test execution in a visual format. You can also run the trace viewer locally by running:

pnpx playwright show-trace path/to/trace.zip

Most CI systems also support extracting trace files, making it easy to debug test failures in your CI pipeline.

This is a powerful tool to assist in writing new tests or debugging of existing ones.

Further Reading

For more in-depth information on running and debugging Playwright tests, consult the official Playwright documentation. It provides comprehensive guides on test execution, configuration, and advanced debugging techniques.