@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/docs/guides/testing.md

@@ -0,0 +1,575 @@
+# Testing
+
+This guide shows you how to write and run tests for your engine and user interfaces.
+
+## What you'll learn
+
+- How to write unit tests for the engine
+- How to test React user interface components
+- How to run tests locally
+
+## Testing engine logic
+
+### Starting from the generated defaults
+
+Alongside `types.ts`, the build generates a `defaults.ts` beside every resource, holding the values a session opens with:
+
+```typescript
+// engine/defaults.ts (generated, do not edit)
+export const defaultContext: Context = {
+    inventory: { Stock: 0, LastRestocked: '' },
+    sales: { Sales: 0 },
+};
+
+export const defaultSettings: Settings = {
+    engine: { DailySales: 10 },
+};
+```
+
+A test spreads those and names only what the case is about:
+
+```typescript
+const context: Context = {
+    ...defaultContext,
+    inventory: { Stock: 100, LastRestocked: '2024-01-01' },
+};
+```
+
+This matters as an engine grows. `Context` is the union of every capability the engine reads or writes, and TypeScript requires all of them, so a test about one capability would otherwise have to write out twenty. The usual escape is `as unknown as Context`, which switches off shape checking for the whole fixture, so the test stops catching the typo it existed to catch. Spreading the defaults keeps both the brevity and the checking, and a capability added later arrives in every fixture already populated instead of breaking each one.
+
+Because they are generated from the same schemas the types are, the values cannot drift from what a real session starts with.
+
+An engine's `defaults.ts` also exports `defaultTeamContext` and `defaultSharedContext`, the same values split by scope to match the generated `TeamContext` and `SharedContext`. They are what an aggregate function's `teams` and `shared` arguments hold (see [Testing an aggregate function](#testing-an-aggregate-function)).
+
+Every capability variable must declare a `default` for this to work. The build says so, naming the capability and the variable, if one does not.
+
+### Testing the Run function
+
+`Init` and `Run` receive a single args object `{ context, settings, meta, participants, callbacks }`. Most of it is the runtime's to supply, so build it with `logicArgs` from `@seriousgaming/sdk/testing` and name only what the test is about:
+
+```typescript
+// engine/logic.test.ts
+import { logicArgs } from '@seriousgaming/sdk/testing';
+import { describe, it, expect } from 'vitest';
+import { defaultSettings, defaultContext } from './defaults';
+import { Run } from './logic';
+import type { Context, Settings } from './types';
+
+describe('Warehouse Engine', () => {
+    it('should decrease stock by daily sales', async () => {
+        const context: Context = {
+            ...defaultContext,
+            inventory: { Stock: 100, LastRestocked: '2024-01-01' },
+        };
+        const settings: Settings = { engine: { ...defaultSettings.engine, DailySales: 10 } };
+
+        const result = await Run(logicArgs.run({ context, settings }));
+
+        expect(result.capabilities.inventory.Stock).toBe(90);
+    });
+
+    it('should not allow negative stock', async () => {
+        const context: Context = {
+            ...defaultContext,
+            inventory: { Stock: 5, LastRestocked: '2024-01-01' },
+        };
+
+        const result = await Run(logicArgs.run({ context, settings: defaultSettings }));
+
+        expect(result.capabilities.inventory.Stock).toBeGreaterThanOrEqual(0);
+    });
+});
+```
+
+The result passes straight to `Run` with no cast: its types come from `Run`'s own, which come from the generated `types.ts`. Everything not named is filled with fixed values:
+
+| Argument       | Default                                                                                                                                                                                              |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `meta`         | `tick: 1` (`0` for `logicArgs.init`), `teamId: 'team-1'`, `index: 0`, `locale: 'en'`, `seed: 'test-seed'`, `runKind: 'session'`, `now` 2026-01-01T00:00:00Z. Pass any of them in `meta` to change it |
+| `participants` | One connected participant, id `'1'`, on the call's team                                                                                                                                              |
+| `callbacks`    | The offline stubs (see [Testing with LLM callbacks](#testing-with-llm-callbacks)). Pass any of them in `callbacks` to replace it                                                                     |
+| `settings`     | None. There is no runtime to resolve them, so pass the generated `defaultSettings`, spread with what the test changes. A resource that declares no settings may leave it out                         |
+
+```typescript
+const args = logicArgs.run({
+    context,
+    settings: defaultSettings,
+    meta: { tick: 3, runKind: 'walkthrough' },
+    state: { BestProfit: 100 },
+});
+```
+
+A step function an engine calls from `Run` takes the same arguments, so `logicArgs.run` builds them too.
+
+### Testing the Init function
+
+`logicArgs.init` is `logicArgs.run` with `meta.tick` at 0, as `Init` sees it:
+
+```typescript
+import { Init } from './logic';
+
+describe('Warehouse Init', () => {
+    it('should initialize with correct default values', async () => {
+        const settings: Settings = { engine: { ...defaultSettings.engine, InitialStock: 500 } };
+
+        const result = await Init(logicArgs.init({ context: defaultContext, settings }));
+
+        expect(result.capabilities.warehouse.Stock).toBe(500);
+        expect(result.capabilities.warehouse.ReorderCount).toBe(0);
+    });
+});
+```
+
+### Testing an aggregate function
+
+`InitAggregate` and `RunAggregate` receive `{ shared, teams, settings, meta, participants, callbacks }`. Pass each team from `defaultTeamContext`, which carries team scope only, and the shared store once, in `shared`. `logicArgs.aggregate` names each team from its `index` and seats one participant on each:
+
+```typescript
+import { logicArgs } from '@seriousgaming/sdk/testing';
+import { defaultSettings, defaultSharedContext, defaultTeamContext } from './defaults';
+import { RunAggregate } from './logic';
+
+function makeTeams(...prices: number[]) {
+    return prices.map((price, index) => ({
+        index,
+        context: { ...defaultTeamContext, price: { Price: price } },
+    }));
+}
+
+it('writes the average price to the shared store', async () => {
+    const result = await RunAggregate(
+        logicArgs.aggregate({
+            shared: { context: defaultSharedContext },
+            teams: makeTeams(4, 6),
+            settings: defaultSettings,
+        })
+    );
+
+    expect(result.shared.capabilities.market?.AverageMarketPrice).toBe(5);
+});
+```
+
+For `InitAggregate`, pass `meta: { tick: 0 }`. A shared capability belongs in `result.shared.capabilities`, never in a `teams` entry: returning one there fails the tick at runtime, so a test that asserts on `result.teams[0].capabilities.market` is asserting on something the runtime would reject.
+
+### Testing hooks, endpoints, validators and tick controllers
+
+Each kind of logic has its own builder, typed from the function it is passed to:
+
+| Builder                    | For                              | Fills, beyond `meta`, `participants` and `callbacks`                                                                                                                                                                                                             |
+| -------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logicArgs.hook`           | A hook's `Run`                   | The roster is the payload's `participant`. The signal defaults to `participantJoin`; name `signal: 'participantMove'` for a move, whose payload it then requires                                                                                                 |
+| `logicArgs.endpoint`       | An endpoint's `Handle` or `Plan` | `team` (`team-1`), `session` (independent, no ticks completed) and `caller`: the team's first participant through `ui`, or pass `caller: { role: 'facilitator' }` (from `session`) or `caller: { role: 'author' }` (from `scenario_editor`, with no `sessionId`) |
+| `logicArgs.validator`      | A validator's `UpdateData`       | `actor`: the roster's first participant                                                                                                                                                                                                                          |
+| `logicArgs.requestTick`    | A validator's `RequestTick`      | `actor`, and `requestedTick: 1`                                                                                                                                                                                                                                  |
+| `logicArgs.tickController` | `GetTickController`              | `teams`: the one team `meta` names, with `context`. `waitingRoomOpen: false`                                                                                                                                                                                     |
+
+```typescript
+const result = await Handle(
+    logicArgs.endpoint({ request: { price: 12 }, context, caller: { role: 'facilitator' } })
+);
+
+const verdict = await UpdateData(
+    logicArgs.validator({ previous, next, settings: defaultSettings })
+);
+
+await Run(
+    logicArgs.hook({
+        signal: 'participantMove',
+        context,
+        participant,
+        fromTeamId: 'team-1',
+        toTeamId: 'team-2',
+        phase: 'departure',
+    })
+);
+```
+
+### Testing with LLM callbacks
+
+The callbacks `logicArgs` fills are offline stubs, the same a test session uses; pass one in `callbacks` to choose its answer. See [Service callbacks are stubbed](./engine-testing.md#service-callbacks-are-stubbed) for what each stub answers and how to override it.
+
+## Testing user interfaces
+
+User interfaces are React components. The SDK scaffold sets up [Vitest](https://vitest.dev/) with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) automatically: `App.test.tsx` is created alongside `App.tsx`.
+
+### How it works
+
+A package is one game, so it has one of each of these at its root:
+
+- `vitest.config.ts`: Vitest config with `jsdom` environment
+- `test-setup.ts`: imports `@testing-library/jest-dom` matchers and sets up cleanup
+
+Each UI's tests sit beside its component: the game UI's are at `ui/src/App.test.tsx`.
+
+### Using render helpers
+
+The SDK provides render helpers that set up all required context providers with sensible defaults. Each UI type has a dedicated helper:
+
+| Helper                         | UI type                       |
+| ------------------------------ | ----------------------------- |
+| `renderUserInterface()`        | Game UIs                      |
+| `renderSettingsEditor()`       | Setup and the scenario editor |
+| `renderSessionUserInterface()` | Session UIs                   |
+
+Every helper accepts an options object for overriding any context value and returns the `@testing-library/react` render result plus any mock functions (`setData`, a settings editor's `updateSettings`, `callbacks`) for assertions.
+
+#### Game UIs
+
+```typescript
+// ui/src/App.test.tsx
+import { describe, it, expect, vi } from 'vitest';
+import { screen, fireEvent } from '@testing-library/react';
+import { renderUserInterface } from '@seriousgaming/sdk/ui/testing';
+import type { Context, Settings } from '../types';
+import App from './App';
+
+const mockData: Context = {
+    inventory: { Stock: 100 },
+    pricing: { Price: 25 },
+};
+
+const mockSettings: Settings = { ui: { MaxPrice: 500 } };
+
+describe('Dashboard', () => {
+    it('renders the current stock', () => {
+        renderUserInterface(<App />, { data: mockData, settings: mockSettings });
+        expect(screen.getByText(/100/)).toBeInTheDocument();
+    });
+
+    it('calls setData when price is changed', () => {
+        const setData = vi.fn();
+        renderUserInterface(<App />, { data: mockData, settings: mockSettings, setData });
+
+        fireEvent.change(screen.getByLabelText(/price/i), { target: { value: '50' } });
+        expect(setData).toHaveBeenCalledWith({
+            pricing: { Price: 50 },
+        });
+    });
+
+    it('can request a tick via callbacks', () => {
+        const requestTick = vi.fn();
+        renderUserInterface(<App />, {
+            data: mockData,
+            settings: mockSettings,
+            callbacks: { requestTick },
+        });
+
+        screen.getByText('Submit').click();
+        expect(requestTick).toHaveBeenCalledOnce();
+    });
+});
+```
+
+Default values when you omit an option:
+
+| Option           | Default                                                                           |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `data`           | `{}`                                                                              |
+| `settings`       | `{}`                                                                              |
+| `completedTicks` | `0`                                                                               |
+| `setData`        | no-op                                                                             |
+| `theme`          | `createMockTheme()` (light mode, MUI palette)                                     |
+| `locale`         | `{ locale: 'en' }`                                                                |
+| `participant`    | `{ id: '1', name: 'Participant 1', index: 0, connected: true, teamId: 'team-1' }` |
+| `participants`   | `[]` (`createMockParticipants(n)` builds a roster)                                |
+| `timer`          | Disabled (no auto-tick)                                                           |
+| `callbacks`      | All present as no-ops                                                             |
+
+Every option, and those of the other two helpers, is listed in the [UI testing API reference](../api/sdk-ui-testing.md#renderuserinterfaceoptions).
+
+A waiting room renders under the game UI's providers, so `renderUserInterface` tests it too. A presentation has no render helper: see [Presentations](./presentation.md#testing).
+
+#### Setup and the scenario editor
+
+The generated `Settings` of a `setup` or `scenario_editor` slot is keyed by the settings resources it lists in `configures`, and every property of each is present, so its generated `defaultSettings` is what a fixture starts from. Writing the settings defaults out by hand instead leaves a copy that rots silently the next time the schema changes.
+
+```typescript
+import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
+import { defaultSettings } from './defaults';
+
+it('calls updateSettings when a value changes', () => {
+    const updateSettings = vi.fn();
+    renderSettingsEditor(<App />, {
+        settings: { ...defaultSettings, engine: { ...defaultSettings.engine, BaseDemand: 100 } },
+        updateSettings,
+    });
+
+    fireEvent.change(screen.getByLabelText(/base demand/i), { target: { value: '200' } });
+    expect(updateSettings).toHaveBeenCalledWith({ engine: { BaseDemand: 200 } });
+});
+```
+
+#### Session UIs
+
+Type the helpers with the surface's generated types: `renderSessionUserInterface<SessionData>`, `createMockTeamState<TeamContext>` and `createMockSharedState<SharedContext>`. Each fixture's context then accepts only capabilities of its own scope, any of them optional, so a shared capability left on a team's fixture fails to compile, as reading one through a team does in the surface. Left untyped, the helpers accept any context.
+
+```typescript
+import {
+    createMockSharedState,
+    createMockTeamState,
+    renderSessionUserInterface,
+} from '@seriousgaming/sdk/ui/testing';
+
+import type { SessionData, SharedContext, TeamContext } from '../types';
+
+it('resets all teams', () => {
+    const resetGame = vi.fn();
+    renderSessionUserInterface<SessionData>(<SessionDashboard />, {
+        sessionData: {
+            // Shared capabilities arrive once, beside the teams. Either half
+            // may be left out, and defaults to empty
+            shared: createMockSharedState<SharedContext>({
+                context: { briefing: { Message: 'Welcome' } },
+            }),
+            teams: {
+                'team-1': createMockTeamState<TeamContext>({ completedTicks: 3 }),
+            },
+        },
+        teams: [{ teamId: 'team-1', index: 0, name: 'Alpha' }],
+        teamConfiguration: { mode: 'independent', max: 6 },
+        callbacks: { resetGame },
+    });
+
+    screen.getByText('Reset All').click();
+    expect(resetGame).toHaveBeenCalledOnce();
+});
+
+it('writes a per-team override', () => {
+    const setData = vi.fn();
+    renderSessionUserInterface<SessionData>(<SessionDashboard />, {
+        sessionData: {
+            teams: {
+                'team-1': createMockTeamState<TeamContext>({ context: { price: { Price: 10 } } }),
+            },
+        },
+        teams: [{ teamId: 'team-1', index: 0, name: 'Alpha' }],
+        setData,
+    });
+
+    fireEvent.change(screen.getByLabelText(/price/i), { target: { value: '20' } });
+    expect(setData).toHaveBeenCalledWith('team-1', { price: { Price: 20 } });
+});
+```
+
+A session UI's `setData` takes the team id first for a team's own capabilities, and the update alone for a shared one. Either form passes its options last, so a delete is asserted as `expect(setData).toHaveBeenCalledWith('team-1', {}, { deletes: [['pinboard', 'Notes', 'p1']] })`.
+
+### Never wire the providers by hand
+
+Always render through these helpers. They supply every context a surface reads, with complete defaults, and each option overrides one value, so a test that needs a particular theme, locale, callback or viewer role passes it as an option. A hand-built provider tree has to supply every callback and every field itself, and it silently stops matching the runtime when the SDK adds one.
+
+### Testing controlled inputs
+
+For inputs that call `setData` on change, use `fireEvent.change` rather than `userEvent.type`. Because `setData` is mocked, the component's displayed value won't update between keystrokes. `fireEvent.change` fires a single synthetic event with the exact target value, which correctly triggers `onChange`:
+
+```typescript
+import { fireEvent } from '@testing-library/react';
+
+it('calls setData when price is changed', () => {
+    const setData = vi.fn();
+    renderUserInterface(<App />, { data: mockData, settings: mockSettings, setData });
+
+    const priceInput = screen.getByLabelText(/price/i);
+    fireEvent.change(priceInput, { target: { value: '50' } });
+
+    expect(setData).toHaveBeenCalledWith({
+        pricing: { Price: 50 },
+    });
+});
+```
+
+### Testing a stateful harness
+
+Where a test keeps the context in local state so the component re-renders after each write, build `setData` with `mergingSetData` from `@seriousgaming/sdk/ui/testing`. It writes as the host does: objects merge recursively, arrays and scalars replace whole, and the paths in `deletes` are removed after the merge. A hand-rolled `{ ...previous, ...patch }` replaces whole capabilities, so a minimal write that is correct in the game fails the test:
+
+```tsx
+import { mergingSetData } from '@seriousgaming/sdk/ui/testing';
+
+const [data, setLocal] = useState(mockData);
+const setData = mergingSetData(setLocal);
+
+setData({}, { deletes: ['pinboard.Notes.p1'] }); // the note's key is gone, not null
+```
+
+### Troubleshooting
+
+**"Invalid hook call" or "Cannot read properties of null (reading 'useContext')"**
+
+Two copies of React are loaded: one from your package and one from the `file://` SDK dependency. Add `resolve.dedupe` to your `vitest.config.ts`, with the SDK packages beside React so a second copy of the SDK cannot hide the providers either:
+
+```typescript
+export default defineConfig({
+    resolve: {
+        dedupe: [
+            'react',
+            'react-dom',
+            '@emotion/react',
+            '@emotion/styled',
+            '@seriousgaming/sdk',
+            '@seriousgaming/deck',
+        ],
+    },
+    // ...
+});
+```
+
+This is already included in the scaffold-generated `vitest.config.ts`.
+
+**"Found multiple elements with the text: X" / DOM accumulation between tests**
+
+React Testing Library cannot auto-detect Vitest's test lifecycle unless `globals: true` is set. Without it, the DOM is not cleaned up between tests. The scaffold-generated `test-setup.ts` handles this explicitly:
+
+```typescript
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+afterEach(cleanup);
+```
+
+If you see stale elements from a previous test appearing in a later test, check that this is present in your `test-setup.ts`.
+
+## Running tests
+
+```bash
+# Run all tests once
+pnpm run test
+
+# Watch mode
+pnpm run test -- --watch
+
+# Specific file
+pnpm run test -- ui/src/App.test.tsx
+```
+
+## The runtime your tests do not reproduce
+
+An engine test imports `logic.ts` straight into Vitest, which runs under **Node**, with Node's full set of globals. Your game's production runtime is a **bare V8 isolate** with only the ECMAScript intrinsics (see [the language environment your logic runs in](./engine.md#the-language-environment-your-logic-runs-in)).
+
+So a unit test cannot tell you that your logic is portable. This passes:
+
+```typescript
+// logic.ts
+export const Run: RunFunction<Context, Settings> = async ({ context }) => {
+    const snapshot = structuredClone(context); // works in Node, throws in production
+    // ...
+};
+```
+
+Its test goes green, because Node has `structuredClone`. The same tick throws `ReferenceError` once deployed.
+
+Two things close the gap, and you should rely on both:
+
+1. **Lint.** A scaffolded package restricts the absent globals inside the directories that hold logic (`engine/`, `tick_controller/`, and each hook's, validator's and endpoint's `logic/`), so `pnpm run lint` flags the reference before you run anything. This is the fastest signal and the one to trust. The rule is deliberately **off** for `*.test.ts` files, because a test legitimately runs in Node
+2. **Exercise the logic through the real environment.** `pnpm run sdk dev` and `pnpm run sdk tick` both run logic in the restricted environment, so they reproduce the production failure. An [engine test](#engine-tests) drives the same execution path, which makes it a stronger portability signal than a direct unit test
+
+The practical rule: unit-test your logic for correctness, and never treat a green unit test as evidence that it will run in production.
+
+### Writes are checked when they happen
+
+A unit test that calls `Init` or `Run` directly checks only what you assert. The runtime also checks each write against the declarations, and two of those checks see nothing until the write happens:
+
+- **A capability outside `writes`.** An engine, aggregate or hook that changes a capability it only reads, or never declared, fails the call
+- **A shared capability from a per-team `Init` or `Run`.** In an aggregate engine, only `InitAggregate` and `RunAggregate` may write shared state. A per-team `Init` that does stops the session starting
+
+Both compare the value before and after the call, so a write that leaves the value as it was passes. An engine that changes a read-only capability only in round 4, or only under one scenario, fails there and nowhere else. `sdk build` does not run your logic, and a one-tick `sdk tick --no-server` passes every path that tick did not take.
+
+So drive every code path that writes through the runtime: an [engine test](#engine-tests) that plays each round, each branch and each scenario, not one tick.
+
+## Best practices
+
+1. **Test what the user sees**: assert on rendered text, input values, and visible state rather than internal component state.
+
+2. **Use `fireEvent.change` for controlled inputs**: `userEvent.type` won't work correctly when the mock `setData`/`updateSettings` doesn't update the displayed value between keystrokes.
+
+3. **Keep context data close to realistic**: populate `mockData` with values that reflect a real game state. Tests that rely on fallback/undefined values hide bugs.
+
+4. **Test edge cases**: zero values, maximum values, empty arrays, and missing optional capabilities.
+
+5. **One `renderApp` helper per test file**: accept `dataOverrides` and `configOverrides` parameters so individual tests can vary only the data they care about.
+
+## Engine tests
+
+Unit tests check one function. An engine test runs the whole game in-process with `createTestSession` from `@seriousgaming/sdk-tools/client`: the session the dev server runs, with its hooks, validators, endpoints and timers, and offline stubs for the platform services. The [Engine testing](./engine-testing.md) guide is the reference: setup, the typed helpers, completion, endpoints, automatic ticks, and stubbing `generateText`.
+
+```bash
+pnpm test:engine
+```
+
+When a Playwright test fails, run the engine tests first. If one fails, the bug is in your logic; if they pass, it is in the UI or its connection to the host.
+
+## Browser E2E tests (Playwright)
+
+Unit and integration tests cover logic and components in isolation. Browser E2E tests verify that your game UI works correctly inside the dev server, including iframe embedding, tick progression, and the full interaction flow.
+
+The SDK provides selectors and helpers via a dedicated subpath export with no Playwright dependency of its own:
+
+```typescript
+import { expect, test } from '@playwright/test';
+import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
+
+test.beforeEach(async () => {
+    await reinitialiseSession(); // a fresh session from the package, started
+});
+
+test('the value rises after a tick', async ({ page }) => {
+    // `?bare` drops the dev console's chrome, so this test is about the game.
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+    await expect(frame.locator('#value')).toHaveText('0');
+
+    // Tick via the game's own control (the starter dashboard wires requestTick)
+    await frame.getByRole('button', { name: 'Next tick' }).click();
+    await expect(frame.locator('#value')).toHaveText('10');
+});
+```
+
+Anything a facilitator can do, a test can do without going through a surface:
+`runCommand({ type: 'tick' })` advances the session, `getState()` reads the
+whole projection, and `runCommand({ type: 'armFault', fault: 'conflict' })`
+makes the 'Try again' path your UI offers reachable. `waitForState` waits for
+something that happens after its command answers, and `advanceClock` moves the
+time of a server started with a `FakeClock` on, so automatic ticks are tested without waiting.
+
+When you create a project with `sdk new package`, a `playwright.config.ts`, the global setup that starts its dev server (`testing/e2e/global-setup.ts`, below) and a `testing/e2e/game.spec.ts` starter are generated automatically.
+
+### A dev server for browser tests
+
+`startDevServer` starts the dev server in your test runner's process, isolated from the one you are working in, and resolves once it answers. It is what `sdk dev --isolated --port auto` runs, without spawning the CLI and parsing its output:
+
+- It takes free ports, so it starts beside your own dev server rather than asking you to stop it
+- It writes no lock file, so `sdk tick` in your terminal still reaches your own server
+- It reads configuration from the package alone, ignoring what you last ran `sdk configure` with
+- Uploads go to a temporary directory, removed by `stop()`
+
+```typescript
+// testing/e2e/global-setup.ts, as the scaffold writes it
+import { dirname } from 'path';
+
+import { startDevServer } from '@seriousgaming/sdk-tools/client';
+import type { FullConfig } from '@playwright/test';
+
+export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
+    const server = await startDevServer({
+        packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
+    });
+    process.env.SERIOUSGAMING_DEV_URL = server.url;
+    return () => server.stop();
+}
+```
+
+`playwright.config.ts` names it as `globalSetup` and sets `use.baseURL` to `process.env.SERIOUSGAMING_DEV_URL`, which each worker reads after the setup has run. Stopping the server is a call in Playwright's own process, so the run ends when its tests do; a `webServer` running `pnpm run sdk dev` is stopped through `pnpm`, never reaches the server, and hangs.
+
+It returns `{ url, assetUrl, stop() }`: `url` is the console and API, and `assetUrl` is where game surfaces are served from. The `@seriousgaming/sdk/e2e` helpers address the server `SERIOUSGAMING_DEV_URL` names, so a test passes them no options; pass `{ url: server.url }` where you hold the server yourself. It also takes `teams`, `participants`, `scenarioId`, `locale`, `clock` (a `FakeClock`) and `callbacks`, as [`createTestSession`](./engine-testing.md) does. Always call `stop()`: the server holds its ports and a file watcher open until then.
+
+To drive it from the CLI as well, set `SERIOUSGAMING_DEV_URL` to its `url`.
+
+See [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) for the full setup guide, all available selectors, and common patterns.
+
+## Next steps
+
+- [Building user interfaces](./ui.md) - Build and develop custom UIs
+- [Creating engines](./engine.md) - Write a testable engine
+- [Engine testing](./engine-testing.md) - Whole-game tests with `createTestSession`
+- [Recipe: Test a user interface](../recipes/test-user-interface.md) - Step-by-step testing walkthrough
+- [Recipe: Test a whole game in-process](../recipes/test-with-engine.md) - In-process engine test setup
+- [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) - Browser-based end-to-end tests