How to write tests

This document explains how to write a few different kinds of tests.

Vitest

We use Vitest (opens in a new tab) to run our automated tests. This section only explain a few basics to get you started, please refer to the official guide (opens in a new tab) for more information.

To run the entire test suite, simply execute the test script from the project root:

1
$ pnpm test
2
# ...
3
# Test Files  14 passed (14)
4
#      Tests  91 passed (91)
5
#   Start at  09:41:22
6
#   Duration  7.11s (transform 4.49s, setup 2ms, collect 22.69s, tests 2.26s)

Vitest will, by default, discover all test files in the entire repository and run them all. We use <NAME>.test.<EXT> (with <EXT> usually being one of .js, .ts, .jsx or .tsx) as the file name pattern, which will be automatically picked up by Vitest.

You can use Vitest’s support for filters (opens in a new tab) to run only a few tests. For example, to only run the tests in the core package, execute:

1
$ pnpm test src/packages/framework/core/
2
# ✓ packages/framework/core/events.test.ts (6)
3
# ✓ packages/framework/core/error.test.ts (3)
4
# ✓ packages/framework/core/Logger.test.ts (7)
5
#
6
# Test Files  3 passed (3)
7
#      Tests  16 passed (16)
8
#   Start at  09:46:47
9
#   Duration  1.96s (transform 2.60s, setup 1ms, collect 3.62s, tests 90ms)

Note
You can also force the execution of a single test (or group of tests) from source code by adding a .only in the test registration (it or describe). .only should never be committed into source control since it effectively hides all other tests from the system. See also Vitest’s --allowOnly option.

Watch mode

Vitest will remain running after executing the test suite when executed locally. It will watch for file changes (similar to Vite’s hot reloading) and re-execute tests that are impacted by these changes (Documentation (opens in a new tab)).

Running Vitest manually

Vitest can be started manually using the following command:

1
$ pnpm exec vitest --help

Creating tests

First, we need some functionality to test. We’ll use the empty app (in src/apps/empty) as a starting point.

Create a new source file:

1
export function multiply(a: number, b: number): number {
2
    return a * b;
3
}

To create tests, simply create a new *.test.ts (or .js etc.) file. In this case, we’ll reuse the multiply file name:

1
import { assert, it } from "vitest"; // (1)
2
import { multiply } from "./math";
3

4
it("multiplies two numbers", () => {
5
    const result = multiply(7, 6);
6
    assert.strictEqual(result, 42); // (2)
7
});

(1)
Imports test helpers from vitest. it (or test) define a new test. describe can be used to group tests together, to share common setup code for example.
(2) assert is used to check the result of the multiplication. assert and expect are available from vitest to write assertions.

For more details, visit Vitest’s API reference (opens in a new tab).

Running our new test is as simple as executing the following command:

1
$ pnpm test src/apps/empty/
2
# ✓ apps/empty/math.test.ts (1)
3
#
4
#  Test Files  1 passed (1)
5
#       Tests  1 passed (1)
6
#    Start at  10:10:42
7
#    Duration  1.76s (transform 1.16s, setup 0ms, collect 1.14s, tests 3ms)
8
#
9
#
10
#  PASS  Waiting for file changes...
11
#        press h to show help, press q to quit

Leave Vitest running and experiment a bit with both the implementation and your test code (for example, try making it fail). Vitest will automatically re-run your test when it detects a change.

To conclude this section, we’ll add another test:

1
// ...
2
it("throws when the result is not a number", () => {
3
    assert.throws(() => multiply(Number.NaN, 5), /Not a number/);
4
});

The test invokes multiply and expects an error to be thrown when the multiplication would result in a NaN value. multiply does not behave in that way, so this test will currently fail:

1
 FAIL  apps/empty/math.test.ts > throws when the result is not a number
2
AssertionError: expected [Function] to throw an error
3
 ❯ apps/empty/math.test.ts:12:12
4
     10|
5
     11| it("throws when the result is not a number", () => {
6
     12|     assert.throws(() => multiply(Number.NaN, 5), /Not a number/);
7
       |            ^
8
     13| });
9
     14|
10

11
  - Expected   "null"
12
  + Received   "undefined"
13

14
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯
15

16
 Test Files  1 failed (1)
17
      Tests  1 failed | 1 passed (2)
18
   Start at  10:14:43
19
   Duration  72ms

To make the test succeed, update the implementation:

1
export function multiply(a: number, b: number): number {
2
    const result = a * b;
3
    if (Number.isNaN(result)) {
4
        throw new Error("Not a number");
5
    }
6
    return result;
7
}

Vitest will now report success:

1
 RERUN  apps/empty/math.ts x10
2

3
 ✓ apps/empty/math.test.ts (2)
4

5
 Test Files  1 passed (1)
6
      Tests  2 passed (2)
7
   Start at  10:17:46
8
   Duration  33ms
9

10

11
 PASS  Waiting for file changes...
12
       press h to show help, press q to quit

UI Tests (browser mode)

Vitest can be used to write simple UI tests. We recommend using the Vitest browser mode (opens in a new tab) which is part of the Vitest API and allows you to run tests natively in the browser.

The repository is already prepared for using Vitest browser mode. It is configured to use playwright as a provider. Hence, you need to install Playwright dependencies before running browser tests:

pnpm exec playwright install

To create a browser mode test, create a test file using the .browser.test.* filename pattern.

In your test file you can import the render function from vitest-browser-react (opens in a new tab) and use it to mount DOM elements. The following example shows how to render a simple component. It is wrapped in the PackageContextProvider, that is needed to inject services and properties into the component tree. The example also demonstrates how to use actual i18n values in the rendered components (for more details see Use real i18n messages in tests).

1
import { PackageContextProvider } from "@open-pioneer/test-utils/react";
2
import { messages, messageLocale } from "open-pioneer:test-support";
3
import { render } from "vitest-browser-react";
4
import { SimpleUiComponent } from "./SimpleUiComponent";
5

6
it("simple ui component is rendered", async () => {
7

8
    const screen = await render(
9
        <PackageContextProvider messages={messages} locale={messageLocale}>
10
            <SimpleUiComponent textToShow="rendered successfully" data-testid="uiDiv "/>
11
        </PackageContextProvider>
12
    );
13
    ...
14
}

A full example for a browser test file can be found in the sample package (sample-package) in SimpleUiComponentent.browser.test.tsx.

It is often more convenient (and faster) to test the React components instead of the complete web component application since there are fewer moving parts and fewer dependencies to mock. However, testing the final application can be great too for automated acceptance tests etc.

Recommended resources:

Vitest Browser Mode: https://vitest.dev/guide/browser/#browser-mode (opens in a new tab)
vitest-browser-react: https://vitest.dev/api/browser/react.html (opens in a new tab)
Our own test utils in @open-pioneer/test-utils

UI Tests (with mocked DOM)

Beside the option to create UI test using the Vitest browser mode, it is also possible to write simple UI tests by simulating a browser environment.

The repository is configured to allow the usage of happy-dom, (see Reference (opens in a new tab)) in your test files using the .test.* filename pattern (not .browser.test.*).

You can use @testing-library/react (opens in a new tab) to render your UI components.

NOTE: We recommend using Vitest browser mode as the happy-dom support will be removed from the starter repository in the future (deprecated).

Use real i18n messages in tests

The module open-pioneer:test-support provides test support helpers for the importing package, such as the actual i18n messages used when running the package in a Trails app.

It exports messages, the i18n messages of the importing package and of all its dependencies. The record can be passed to the messages property of PackageContextProvider from @open-pioneer/test-utils/react.

The module also exports messageLocale, the locale of these messages.

Example usage:

1
// Render a component with the real messages of its package.
2
import { PackageContextProvider } from "@open-pioneer/test-utils/react";
3
import { render } from "@testing-library/react"; // or import { render } from "vitest-browser-react";
4
import { messages, messageLocale } from "open-pioneer:test-support"; // (1)
5

6
render(
7
    // (2)
8
    <PackageContextProvider messages={messages} locale={messageLocale}>
9
        <MyComponent />
10
    </PackageContextProvider>
11
);

(1) Import messages and messageLocale
(2) Pass the imported messages and messageLocaleto the PackageContextProvider so that they are used in the components that are rendered in the test.

By default, the messages are returned in the first locale listed in the i18n array of the package’s ‘build.config.mjs’. A different locale can be requested with a query, for example:

1
import { messages, messageLocale } from "open-pioneer:test-support?locale=de";

This module is designed to be used in combination with the @open-pioneer/test-utils package and can only be imported in tests.

Test utilities

The package @open-pioneer/test-utils provides helpers to test components of an Open Pioneer Trails application:

The application itself (that is, the web component). Web components can be mounted in the DOM and their children can be searched.
React components with dependencies to services, properties etc. Test dependencies and data can be provided in such a way that the component renders into the DOM without any changes to the component’s implementation.
Service instances can be created with test references and properties.

For more details, take a look at that package’s README and its own tests.