@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.2

package/lib/e2e.d.ts

@@ -0,0 +1,238 @@
+/**
+ * End-to-end testing helpers for Serious Gaming SDK consumers.
+ *
+ * Selectors and API helpers for writing Playwright tests against a game running
+ * on the dev server. No dependency on Playwright itself — pass the selectors to
+ * your own `page.locator()` / `page.frameLocator()` calls.
+ *
+ * What you drive is your own game's surface inside the iframe; the console
+ * around it is a handful of URLs and one drawer, which is why this module is
+ * mostly URLs. Three things are worth knowing before writing a test:
+ *
+ * - Every surface is directly addressable. `/team/2/player/1` is the first
+ *   participant of the second team, with no lookup and no redirect.
+ * - `?bare` removes the dev chrome entirely, so a change to the console cannot
+ *   fail a test about your game. {@link DEV_SERVER.bare} adds it to any URL.
+ * - The helpers address the server `SERIOUSGAMING_DEV_URL` names, which is
+ *   what a Playwright `globalSetup` running `startDevServer` sets, so a test
+ *   on free ports passes no options. `{ url }` or `{ port }` picks another.
+ *
+ * @example
+ * ```typescript
+ * import { DEV_SERVER, runCommand, getState } from '@seriousgaming/sdk/e2e';
+ *
+ * test('the dashboard shows the tick', async ({ page }) => {
+ *     await runCommand({ type: 'reset' });
+ *     await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+ *
+ *     const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+ *     await expect(frame.locator('#tick')).toHaveText('0');
+ *
+ *     await runCommand({ type: 'tick' });
+ *     await expect(frame.locator('#tick')).toHaveText('1');
+ * });
+ * ```
+ */
+import type { RunKind } from './build/signatures.js';
+import type { Command, MutationCommand, QueryCommand, QueryResult } from './commands.js';
+import type { MutationResult, StateProjection } from './projection.js';
+export type { Command, MutationCommand, MutationResult, QueryCommand, QueryResult, StateProjection, };
+/**
+ * Default port the SDK dev server runs on.
+ *
+ * @internal Read {@link DEV_SERVER}`.DEFAULT_PORT` instead.
+ */
+export declare const DEV_SERVER_DEFAULT_PORT = 3000;
+/**
+ * Selectors and URLs for the dev console.
+ *
+ * `selectors` values are CSS attribute selectors over `data-testid`. The set is
+ * deliberately small: the console is chrome around your game, and a test that
+ * drove the chrome would be a test of the SDK rather than of the game.
+ */
+export declare const DEV_SERVER: {
+    /** Default port the dev server runs on. */
+    readonly DEFAULT_PORT: 3000;
+    readonly selectors: {
+        /**
+         * The drawer handle. Bottom-right by default, and movable to any
+         * corner, so locate it by this selector rather than by position. Its
+         * presence is the signal that the console has mounted and connected —
+         * wait for it before pressing a key the console listens for.
+         */
+        readonly devDrawerHandle: "[data-testid=\"dev-drawer-handle\"]";
+        /** The dev drawer itself, opened with the backtick key. */
+        readonly devDrawer: "[data-testid=\"dev-drawer\"]";
+        /** The drawer's locale control. */
+        readonly localeSelect: "[data-testid=\"locale\"]";
+        /**
+         * The host's Play control, which commits the configuration step and
+         * starts the session. Present only while the step is outstanding, and
+         * only for a game with a `setup` slot.
+         */
+        readonly play: "[data-testid=\"play\"]";
+        /** The rendered chapter on the guide page. */
+        readonly guideContent: "[data-testid=\"guide-content\"]";
+        /** The team sheets on the print page. */
+        readonly printSheets: "[data-testid=\"print-sheets\"]";
+    };
+    /** The console: the game's own session surface, with dev chrome around it. */
+    readonly consoleUrl: () => string;
+    /**
+     * One participant's surface. `team` and `participant` are both 1-based,
+     * exactly as they read in the URL.
+     */
+    readonly playerUrl: (team: number, participant?: number) => string;
+    /** A team's surface with no participant identity and no presence (§13.3). */
+    readonly observeUrl: (team: number) => string;
+    /** A team's waiting-room surface (§6.14). */
+    readonly waitingRoomUrl: (team: number) => string;
+    /**
+     * What a facilitator hands out: it asks which participant you are, or opens
+     * straight into their surface when the team holds one.
+     */
+    readonly joinUrl: (team: number) => string;
+    /** The setup surface, before the session starts (§8.3). */
+    readonly setupUrl: () => string;
+    /**
+     * The scenario editor, on one scenario (§6.7.1).
+     *
+     * It is always opened on a scenario: an editor with nowhere to save is one
+     * that wastes the work done in it. In the console this is reached from the
+     * dev drawer's Scenario tab rather than typed.
+     */
+    readonly scenarioEditorUrl: (scenario: string) => string;
+    /** The facilitator guide (§6.9). */
+    readonly guideUrl: () => string;
+    /** One printable sheet per team. */
+    readonly printUrl: () => string;
+    /**
+     * The same URL with the dev chrome removed: exactly what a participant
+     * sees, which is what a test about your game should drive.
+     */
+    readonly bare: (url: string) => string;
+    /**
+     * The `frameLocator` selector for a surface's iframe, by its identifier.
+     * A game holds one of each kind, so the identifier is the slot: `ui`,
+     * `session`, `waiting_room`, `setup` or `scenario_editor`.
+     *
+     * @example
+     * ```typescript
+     * const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+     * ```
+     */
+    readonly iframeSelector: (identifier: string) => string;
+    /** A full URL to a dev server endpoint. */
+    readonly apiUrl: (path: string, port?: number) => string;
+};
+/**
+ * Which dev server a helper talks to. With neither field set, the server
+ * `SERIOUSGAMING_DEV_URL` names (as `startDevServer` in a Playwright
+ * `globalSetup` sets it), or else `localhost` on {@link DEV_SERVER_DEFAULT_PORT}.
+ */
+export interface DevServerOptions {
+    /** The server's address, such as `startDevServer()`'s `url`. Wins over `port`. */
+    url?: string;
+    /** Dev server port on `localhost`. */
+    port?: number;
+    /**
+     * Which run to address: the session (the default), or the walkthrough
+     * beside it (§5.7). The first command sent to the walkthrough builds it.
+     */
+    run?: RunKind;
+}
+/**
+ * Run one command against the running session.
+ *
+ * The same closed command set the console and the CLI use, so anything you can
+ * do by hand you can do from a test: `{ type: 'tick' }`, `{ type: 'reset' }`,
+ * `{ type: 'updateContext', payload: { … } }`, `{ type: 'addTeam' }`. It is
+ * typed against that set, so a misspelled command or field fails to compile
+ * rather than coming back as a 400.
+ *
+ * A mutation settles as `{ ok: true }` or `{ ok: false, outcome }`: a refusal
+ * is an answer rather than a throw, since a tick past the limit is an answer,
+ * not a fault. A read (`getState`, `callEndpoint`, `getPastState`,
+ * `getAllTeamsParticipants`) answers with that read's own result; use
+ * {@link getState} for the common one. Only a transport failure throws, and
+ * so does a command the server does not recognise.
+ */
+export declare function runCommand(command: MutationCommand, options?: DevServerOptions): Promise<MutationResult>;
+export declare function runCommand(command: QueryCommand, options?: DevServerOptions): Promise<QueryResult>;
+/**
+ * The whole session, as one projection: teams, contexts, participants, the
+ * resolved configuration, the timer, and anything the runtime has gone wrong
+ * about. Assert on state without going through a surface.
+ *
+ * @throws if the server responds with a non-OK status.
+ */
+export declare function getState(options?: DevServerOptions): Promise<StateProjection>;
+/**
+ * Return the session to tick 0, so one test does not inherit another's state.
+ * Call it in `test.beforeEach`.
+ *
+ * **It leaves the session started.** The tick counter goes back to zero and
+ * the contexts with it; the waiting room is not reopened, and a game that owes
+ * a configuration step is not returned to it. Only `{ type: 'reconfigure' }`
+ * goes back to the configuration step, and a game with a `setup` slot needs
+ * an explicit `{ type: 'play' }` before any player URL has a game behind it. A test that assumed otherwise spends its time looking at an empty
+ * player URL.
+ *
+ * @throws if the server responds with a non-OK status.
+ */
+export declare function resetSession(options?: DevServerOptions): Promise<void>;
+export interface ReinitialiseOptions extends DevServerOptions {
+    /** Teams to start with. Omit to keep the count the session has. */
+    teams?: number;
+    /** Participants per team: one count, or one per team. Zero is allowed. */
+    participants?: number | number[];
+    /**
+     * A scenario to start on. Omit for the game's default, as a fresh
+     * `sdk dev` would; pass `null` for the settings defaults.
+     */
+    scenarioId?: string | null;
+    locale?: string;
+    /**
+     * Press Play on a game with a configuration step (§8.3). Default `true`,
+     * so every player URL has a game behind it; `false` to test the step.
+     */
+    play?: boolean;
+}
+/**
+ * Start the session again from the package, as a test's known starting point.
+ *
+ * Wider than {@link resetSession}, which returns to tick 0 but keeps the team
+ * count, roster, scenario and locale an earlier test left behind. This
+ * re-resolves them, presses Play where the game has a configuration step, and
+ * disarms any fault an earlier test armed. The waiting room is left as it is;
+ * open or close it with `{ type: 'setWaitingRoom', open }`.
+ *
+ * @throws if the session refuses, for instance a team count outside the game's
+ * bounds.
+ */
+export declare function reinitialiseSession(options?: ReinitialiseOptions): Promise<void>;
+export interface WaitOptions extends DevServerOptions {
+    /** Give up after this long. Default 10 seconds. */
+    timeout?: number;
+    /** How often to look. Default 100 milliseconds. */
+    interval?: number;
+}
+/**
+ * Wait until the session satisfies `predicate`, and return the state that did.
+ *
+ * For something that happens after the command that caused it has answered:
+ * an automatic tick, a hook's write, a participant connecting when a page
+ * opens. Poll the session rather than sleeping for a guess at how long it
+ * takes.
+ *
+ * @throws when `timeout` passes first, with the last state it saw.
+ */
+export declare function waitForState(predicate: (state: StateProjection) => boolean, options?: WaitOptions): Promise<StateProjection>;
+/**
+ * Move the clock of a dev server started with `--fake-clock` forward, running
+ * every automatic tick that falls due on the way (§11). Resolves once they
+ * have run.
+ *
+ * @throws when the server runs on the real clock.
+ */
+export declare function advanceClock(ms: number, options?: DevServerOptions): Promise<void>;

package/lib/e2e.js

@@ -0,0 +1,248 @@
+/**
+ * End-to-end testing helpers for Serious Gaming SDK consumers.
+ *
+ * Selectors and API helpers for writing Playwright tests against a game running
+ * on the dev server. No dependency on Playwright itself — pass the selectors to
+ * your own `page.locator()` / `page.frameLocator()` calls.
+ *
+ * What you drive is your own game's surface inside the iframe; the console
+ * around it is a handful of URLs and one drawer, which is why this module is
+ * mostly URLs. Three things are worth knowing before writing a test:
+ *
+ * - Every surface is directly addressable. `/team/2/player/1` is the first
+ *   participant of the second team, with no lookup and no redirect.
+ * - `?bare` removes the dev chrome entirely, so a change to the console cannot
+ *   fail a test about your game. {@link DEV_SERVER.bare} adds it to any URL.
+ * - The helpers address the server `SERIOUSGAMING_DEV_URL` names, which is
+ *   what a Playwright `globalSetup` running `startDevServer` sets, so a test
+ *   on free ports passes no options. `{ url }` or `{ port }` picks another.
+ *
+ * @example
+ * ```typescript
+ * import { DEV_SERVER, runCommand, getState } from '@seriousgaming/sdk/e2e';
+ *
+ * test('the dashboard shows the tick', async ({ page }) => {
+ *     await runCommand({ type: 'reset' });
+ *     await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+ *
+ *     const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+ *     await expect(frame.locator('#tick')).toHaveText('0');
+ *
+ *     await runCommand({ type: 'tick' });
+ *     await expect(frame.locator('#tick')).toHaveText('1');
+ * });
+ * ```
+ */
+/**
+ * Default port the SDK dev server runs on.
+ *
+ * @internal Read {@link DEV_SERVER}`.DEFAULT_PORT` instead.
+ */
+export const DEV_SERVER_DEFAULT_PORT = 3000;
+/**
+ * Selectors and URLs for the dev console.
+ *
+ * `selectors` values are CSS attribute selectors over `data-testid`. The set is
+ * deliberately small: the console is chrome around your game, and a test that
+ * drove the chrome would be a test of the SDK rather than of the game.
+ */
+export const DEV_SERVER = {
+    /** Default port the dev server runs on. */
+    DEFAULT_PORT: DEV_SERVER_DEFAULT_PORT,
+    selectors: {
+        /**
+         * The drawer handle. Bottom-right by default, and movable to any
+         * corner, so locate it by this selector rather than by position. Its
+         * presence is the signal that the console has mounted and connected —
+         * wait for it before pressing a key the console listens for.
+         */
+        devDrawerHandle: '[data-testid="dev-drawer-handle"]',
+        /** The dev drawer itself, opened with the backtick key. */
+        devDrawer: '[data-testid="dev-drawer"]',
+        /** The drawer's locale control. */
+        localeSelect: '[data-testid="locale"]',
+        /**
+         * The host's Play control, which commits the configuration step and
+         * starts the session. Present only while the step is outstanding, and
+         * only for a game with a `setup` slot.
+         */
+        play: '[data-testid="play"]',
+        /** The rendered chapter on the guide page. */
+        guideContent: '[data-testid="guide-content"]',
+        /** The team sheets on the print page. */
+        printSheets: '[data-testid="print-sheets"]',
+    },
+    /** The console: the game's own session surface, with dev chrome around it. */
+    consoleUrl: () => '/',
+    /**
+     * One participant's surface. `team` and `participant` are both 1-based,
+     * exactly as they read in the URL.
+     */
+    playerUrl: (team, participant = 1) => `/team/${team}/player/${participant}`,
+    /** A team's surface with no participant identity and no presence (§13.3). */
+    observeUrl: (team) => `/team/${team}/observe`,
+    /** A team's waiting-room surface (§6.14). */
+    waitingRoomUrl: (team) => `/team/${team}/waiting-room`,
+    /**
+     * What a facilitator hands out: it asks which participant you are, or opens
+     * straight into their surface when the team holds one.
+     */
+    joinUrl: (team) => `/team/${team}/join`,
+    /** The setup surface, before the session starts (§8.3). */
+    setupUrl: () => '/setup',
+    /**
+     * The scenario editor, on one scenario (§6.7.1).
+     *
+     * It is always opened on a scenario: an editor with nowhere to save is one
+     * that wastes the work done in it. In the console this is reached from the
+     * dev drawer's Scenario tab rather than typed.
+     */
+    scenarioEditorUrl: (scenario) => `/scenario-editor?scenario=${encodeURIComponent(scenario)}`,
+    /** The facilitator guide (§6.9). */
+    guideUrl: () => '/guide',
+    /** One printable sheet per team. */
+    printUrl: () => '/print',
+    /**
+     * The same URL with the dev chrome removed: exactly what a participant
+     * sees, which is what a test about your game should drive.
+     */
+    bare: (url) => (url.includes('?') ? `${url}&bare` : `${url}?bare`),
+    /**
+     * The `frameLocator` selector for a surface's iframe, by its identifier.
+     * A game holds one of each kind, so the identifier is the slot: `ui`,
+     * `session`, `waiting_room`, `setup` or `scenario_editor`.
+     *
+     * @example
+     * ```typescript
+     * const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+     * ```
+     */
+    iframeSelector: (identifier) => `iframe[title="${identifier}"]`,
+    /** A full URL to a dev server endpoint. */
+    apiUrl: (path, port = DEV_SERVER_DEFAULT_PORT) => `http://localhost:${port}${path}`,
+};
+/** The variable naming the dev server, read by these helpers and by the CLI. */
+const DEV_URL_ENV_VAR = 'SERIOUSGAMING_DEV_URL';
+function serverOrigin(options) {
+    if (options.url !== undefined)
+        return options.url.replace(/\/+$/, '');
+    if (options.port !== undefined)
+        return `http://localhost:${options.port}`;
+    // Read through `globalThis`: this module also loads where there is no `process`.
+    const environment = globalThis
+        .process?.env;
+    const named = environment?.[DEV_URL_ENV_VAR];
+    return named ? named.replace(/\/+$/, '') : `http://localhost:${DEV_SERVER_DEFAULT_PORT}`;
+}
+function commandUrl(path, options) {
+    const url = `${serverOrigin(options)}${path}`;
+    return options.run === 'walkthrough' ? `${url}?run=walkthrough` : url;
+}
+export async function runCommand(command, options = {}) {
+    const response = await fetch(commandUrl('/api/command', options), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(command),
+    });
+    if (!response.ok) {
+        const body = (await response.json().catch(() => null));
+        throw new Error(`runCommand failed: HTTP ${response.status}${body?.error ? `: ${body.error}` : ''}`);
+    }
+    return (await response.json());
+}
+/**
+ * The whole session, as one projection: teams, contexts, participants, the
+ * resolved configuration, the timer, and anything the runtime has gone wrong
+ * about. Assert on state without going through a surface.
+ *
+ * @throws if the server responds with a non-OK status.
+ */
+export async function getState(options = {}) {
+    const response = await fetch(commandUrl('/api/state', options));
+    if (!response.ok) {
+        throw new Error(`getState failed: HTTP ${response.status}`);
+    }
+    return (await response.json());
+}
+/**
+ * Return the session to tick 0, so one test does not inherit another's state.
+ * Call it in `test.beforeEach`.
+ *
+ * **It leaves the session started.** The tick counter goes back to zero and
+ * the contexts with it; the waiting room is not reopened, and a game that owes
+ * a configuration step is not returned to it. Only `{ type: 'reconfigure' }`
+ * goes back to the configuration step, and a game with a `setup` slot needs
+ * an explicit `{ type: 'play' }` before any player URL has a game behind it. A test that assumed otherwise spends its time looking at an empty
+ * player URL.
+ *
+ * @throws if the server responds with a non-OK status.
+ */
+export async function resetSession(options = {}) {
+    await runCommand({ type: 'reset' }, options);
+}
+/**
+ * Start the session again from the package, as a test's known starting point.
+ *
+ * Wider than {@link resetSession}, which returns to tick 0 but keeps the team
+ * count, roster, scenario and locale an earlier test left behind. This
+ * re-resolves them, presses Play where the game has a configuration step, and
+ * disarms any fault an earlier test armed. The waiting room is left as it is;
+ * open or close it with `{ type: 'setWaitingRoom', open }`.
+ *
+ * @throws if the session refuses, for instance a team count outside the game's
+ * bounds.
+ */
+export async function reinitialiseSession(options = {}) {
+    const { teams, participants, scenarioId, locale, play = true, ...server } = options;
+    const result = await runCommand({
+        type: 'reinitialise',
+        ...(teams === undefined ? {} : { teams }),
+        ...(participants === undefined ? {} : { participants }),
+        ...(scenarioId === undefined ? {} : { scenarioId }),
+        ...(locale === undefined ? {} : { locale }),
+    }, server);
+    if (!result.ok)
+        throw new Error(`reinitialiseSession refused: ${result.outcome.message ?? result.outcome.kind}`);
+    const state = await getState(server);
+    for (const armed of state.faults) {
+        await runCommand({ type: 'disarmFault', fault: armed.kind }, server);
+    }
+    if (play && state.session.inSetup) {
+        await runCommand({ type: 'play' }, server);
+    }
+}
+/**
+ * Wait until the session satisfies `predicate`, and return the state that did.
+ *
+ * For something that happens after the command that caused it has answered:
+ * an automatic tick, a hook's write, a participant connecting when a page
+ * opens. Poll the session rather than sleeping for a guess at how long it
+ * takes.
+ *
+ * @throws when `timeout` passes first, with the last state it saw.
+ */
+export async function waitForState(predicate, options = {}) {
+    const { timeout = 10_000, interval = 100, ...server } = options;
+    const deadline = Date.now() + timeout;
+    for (;;) {
+        const state = await getState(server);
+        if (predicate(state))
+            return state;
+        if (Date.now() >= deadline) {
+            throw new Error(`waitForState timed out after ${timeout}ms with ${state.session.completedTicks} ticks completed`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+}
+/**
+ * Move the clock of a dev server started with `--fake-clock` forward, running
+ * every automatic tick that falls due on the way (§11). Resolves once they
+ * have run.
+ *
+ * @throws when the server runs on the real clock.
+ */
+export async function advanceClock(ms, options = {}) {
+    const result = await runCommand({ type: 'advanceClock', byMs: ms }, options);
+    if (!result.ok)
+        throw new Error(`advanceClock refused: ${result.outcome.message ?? result.outcome.kind}`);
+}