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

package/lib/ui/testing.d.ts

@@ -0,0 +1,365 @@
+import { type RenderResult } from '@testing-library/react';
+import type { Participant, SettingsEditorCallbacks } from '../build/callbacks.js';
+import type { SessionUserInterfaceCallbacks } from '../build/callbacks.js';
+import type { ThemePreference, UserInterfaceCallbacks } from '../build/callbacks.js';
+import { type ContextUpdate } from '../build/context-merge.js';
+import type { TimerState } from '../build/timer.js';
+import type { ValidationRejection } from '../build/validators.js';
+import type { SessionData, SharedState, TeamState } from './SessionUserInterfaceDataContext.js';
+import type { SessionHookFailure } from './SessionUserInterfaceHookFailuresContext.js';
+import type { HostOverlay } from './SessionUserInterfaceHostOverlaysContext.js';
+import type { SessionUserInterfaceLocale } from './SessionUserInterfaceLocaleContext.js';
+import type { SessionMeta } from './SessionUserInterfaceMetaContext.js';
+import type { TeamConfiguration } from './SessionUserInterfaceTeamConfigurationContext.js';
+import type { TeamLinks } from './SessionUserInterfaceTeamLinksContext.js';
+import type { TeamInfo } from './SessionUserInterfaceTeamsContext.js';
+import type { SessionUserInterfaceTheme } from './SessionUserInterfaceThemeContext.js';
+import type { WalkthroughLink } from './SessionUserInterfaceWalkthroughLinkContext.js';
+import type { SettingsEditorLocale } from './SettingsEditorLocaleContext.js';
+import type { SettingsEditorTheme } from './SettingsEditorThemeContext.js';
+import { type SetDataOptions } from './UserInterfaceDataContext.js';
+import type { UserInterfaceLocale } from './UserInterfaceLocaleContext.js';
+import { type OwnTeamJoinLink } from './UserInterfaceOwnTeamJoinLinkContext.js';
+import type { RunKind } from './UserInterfaceRunKindContext.js';
+import type { UserInterfaceTheme } from './UserInterfaceThemeContext.js';
+import type { ViewerRole } from './UserInterfaceViewerRoleContext.js';
+/**
+ * Creates a valid UserInterfaceTheme for use in tests.
+ *
+ * @example
+ * // Basic usage — light mode with default MUI palette
+ * <UserInterfaceThemeContext.Provider value={createMockTheme()}>
+ *
+ * @example
+ * // Override mode or colours
+ * <UserInterfaceThemeContext.Provider value={createMockTheme({ mode: 'dark' })}>
+ */
+export declare function createMockTheme(overrides?: Partial<UserInterfaceTheme>): UserInterfaceTheme;
+/**
+ * Creates a valid SettingsEditorTheme for use in tests.
+ *
+ * @example
+ * <SettingsEditorThemeContext.Provider value={createMockSettingsEditorTheme()}>
+ */
+export declare function createMockSettingsEditorTheme(overrides?: Partial<SettingsEditorTheme>): SettingsEditorTheme;
+/**
+ * Creates a valid SessionUserInterfaceTheme for use in tests.
+ */
+export declare function createMockSessionTheme(overrides?: Partial<SessionUserInterfaceTheme>): SessionUserInterfaceTheme;
+/**
+ * Creates a valid Participant for use in tests — the caller's own
+ * identity, as returned by `useUserInterfaceParticipant()`.
+ *
+ * @example
+ * // The caller, with a custom name
+ * renderUserInterface(<App />, { participant: createMockParticipant({ name: 'Alice' }) });
+ */
+export declare function createMockParticipant(overrides?: Partial<Participant>): Participant;
+/**
+ * Creates a roster of participants for use in tests — the list returned by
+ * `useUserInterfaceParticipants()` (and the session equivalent, which
+ * shares the same shape). Ids, names, and indices follow the runtime's
+ * conventions (`id` is `String(index + 1)`, `name` is `Participant N`), and
+ * every entry is `connected` by default.
+ *
+ * @example
+ * // A team of three, all online
+ * renderUserInterface(<App />, { participants: createMockParticipants(3) });
+ */
+export declare function createMockParticipants(count?: number, teamId?: string): Participant[];
+/**
+ * What a fixture may put in a context typed `T`: any capability `T` holds,
+ * each optional, and nothing else, so a capability of the wrong scope fails to
+ * compile. Left at its default, `T` accepts any object, as before.
+ */
+type FixtureContext<T> = Record<string, unknown> extends T ? object : Partial<T>;
+/**
+ * A `TeamState` for a session-surface fixture, with the fields a test rarely
+ * cares about filled in.
+ *
+ * `revision` is the reason this exists. It is required, because the wrapper
+ * needs a baseline to compare an `updateTeamState` delta against, but no
+ * surface ever reads it, so making every fixture carry one would be friction
+ * for a field with no meaning to the test.
+ *
+ * Type it with the surface's generated `TeamContext`, and a shared capability
+ * left on a team's fixture fails to compile, as reading one through a team
+ * does in the surface. Capabilities the fixture leaves out are absent.
+ *
+ * ```typescript
+ * import type { TeamContext } from '../types';
+ *
+ * createMockTeamState<TeamContext>({ context: { price: { Price: 5 } } });
+ * ```
+ */
+export declare function createMockTeamState<T extends object = Record<string, unknown>>(overrides?: Partial<Omit<TeamState<T>, 'context'>> & {
+    context?: FixtureContext<T>;
+}): TeamState<T>;
+/**
+ * A `SharedState` for a session-surface fixture: the shared store's context,
+ * with a `revision` filled in for the same reason {@link createMockTeamState}
+ * fills one. Type it with the surface's generated `SharedContext`.
+ *
+ * ```typescript
+ * createMockSharedState<SharedContext>({ context: { market: { Price: 5 } } });
+ * ```
+ */
+export declare function createMockSharedState<T extends object = Record<string, unknown>>(overrides?: Partial<Omit<SharedState<T>, 'context'>> & {
+    context?: FixtureContext<T>;
+}): SharedState<T>;
+/**
+ * A `setData` for a stateful test harness that writes the way the host does:
+ * objects merge recursively, arrays, scalars and `null` replace whole, and
+ * any `deletes` are removed after the merge.
+ *
+ * A hand-rolled `{ ...previous, ...patch }` does not. It replaces a whole
+ * capability with whatever the patch names, so a minimal write (the shape
+ * every concurrency-safe surface sends) appears to wipe every field it did
+ * not mention. Tests then fail on writes that are correct in production, or
+ * worse, pass on writes that are not (#520).
+ *
+ * ```tsx
+ * const [data, setLocal] = useState(mockData);
+ * const setData = mergingSetData(setLocal);
+ * setData({}, { deletes: [`pinboard.Notes.${noteId}`] });
+ * ```
+ *
+ * Wrap it in a `vi.fn()` when the test also asserts on the payload.
+ */
+export declare function mergingSetData<T extends object>(setLocal: (updater: (previous: T) => T) => void): (patch: Record<string, unknown>, options?: SetDataOptions) => void;
+export type RenderUserInterfaceOptions = {
+    /**
+     * The surface's context. Typed as `object` rather than
+     * `Record<string, unknown>` for the same reason {@link mergingSetData} is:
+     * a generated `Context` is an interface, an interface has no implicit index
+     * signature, and the tighter type would reject the one value every caller
+     * actually holds.
+     */
+    data?: object;
+    /** The surface's settings, keyed by settings identifier (§8). */
+    settings?: unknown;
+    /** Ticks completed, surfaced through `useUserInterfaceData().completedTicks`. */
+    completedTicks?: number;
+    /**
+     * Whether a round is being processed, surfaced through
+     * `useUserInterfaceData().isRoundProcessing`. Defaults to false, which is
+     * the state a surface spends nearly all its time in.
+     */
+    isRoundProcessing?: boolean;
+    setData?: (update: Partial<Record<string, unknown>>) => void;
+    /**
+     * The key the host would send on `init` (§12.2), which `useViewerStorage`
+     * namespaces by. Defaults to a fixed test key; give two renders different
+     * keys to show their stored values stay apart.
+     */
+    sessionKey?: string;
+    theme?: UserInterfaceTheme;
+    themePreference?: ThemePreference;
+    locale?: UserInterfaceLocale;
+    /**
+     * Viewer role for the render. Defaults to `'participant'`. Pass
+     * `'observer'` to exercise the observation path, where `participant`
+     * defaults to `null` (an observer has no caller identity).
+     */
+    viewerRole?: ViewerRole;
+    /**
+     * Which kind of run this surface belongs to, read by `useRunKind()`.
+     * Defaults to `'session'`. Pass `'walkthrough'` to exercise the
+     * demonstration path (§5.7).
+     */
+    runKind?: RunKind;
+    participant?: Participant | null;
+    participants?: Participant[];
+    teams?: TeamInfo[];
+    /**
+     * The team the surface renders, read by `useUserInterfaceOwnTeam()`. Defaults to the
+     * participant's team resolved against `teams`, so a test that already sets
+     * both needs nothing extra; set it explicitly to cover an observer, which
+     * has no participant to derive it from.
+     */
+    ownTeam?: TeamInfo | null;
+    /**
+     * How to join the rendered team, read by `useUserInterfaceOwnTeamJoinLink()`. Defaults to
+     * `null`, matching a surface whose host has not delivered it yet.
+     */
+    ownTeamJoinLink?: OwnTeamJoinLink | null;
+    timer?: TimerState;
+    /**
+     * Validator rejections the host has returned for the most recent write,
+     * read by `useUserInterfaceValidationRejections()`. Defaults to empty, so a
+     * surface that renders them is renderable without saying anything; pass a
+     * list to exercise what it shows when a write is refused.
+     */
+    validationRejections?: ValidationRejection[];
+    /** Spy for the rejection channel's `clearRejections`. Defaults to a no-op. */
+    clearRejections?: () => void;
+    callbacks?: Partial<UserInterfaceCallbacks>;
+    blobPrefix?: string;
+    scenarioAssetPrefix?: string;
+    sharedAssetPrefix?: string;
+};
+export type RenderUserInterfaceResult = RenderResult & {
+    setData: (update: Partial<Record<string, unknown>>) => void;
+    callbacks: UserInterfaceCallbacks;
+};
+/**
+ * Renders a component wrapped in all UserInterface context providers with
+ * sensible defaults. Override any context value via the options object.
+ *
+ * Returns the standard `@testing-library/react` render result plus the mock
+ * `setData` and resolved `callbacks` for assertions.
+ *
+ * Callbacks you do not supply default to no-ops rather than spies, so pass your
+ * own `vi.fn()` for any you intend to assert on.
+ *
+ * @example
+ * ```tsx
+ * const requestTick = vi.fn();
+ * const { setData } = renderUserInterface(<App />, {
+ *   data: { 'com.example.cap': { Score: 42 } },
+ *   settings: { scoring: { MaxScore: 100 } },
+ *   callbacks: { requestTick },
+ * });
+ *
+ * fireEvent.click(screen.getByText('Submit'));
+ * expect(requestTick).toHaveBeenCalled();
+ * ```
+ */
+export declare function renderUserInterface(ui: React.ReactElement, options?: RenderUserInterfaceOptions): RenderUserInterfaceResult;
+export type RenderSettingsEditorOptions = {
+    /**
+     * The settings the editor is seeded with, keyed by settings identifier:
+     * typically the slot's generated `defaultSettings`.
+     */
+    settings?: object;
+    updateSettings?: (update: Partial<Record<string, unknown>>) => Promise<void> | void;
+    /** Defaults to the keys of `settings`, as the host's `setSettings` makes it. */
+    configures?: string[];
+    /**
+     * The key the host would send on `init` (§12.2), which `useViewerStorage`
+     * namespaces by. Defaults to a fixed test key; give two renders different
+     * keys to show their stored values stay apart.
+     */
+    sessionKey?: string;
+    theme?: SettingsEditorTheme;
+    themePreference?: ThemePreference;
+    locale?: SettingsEditorLocale;
+    callbacks?: Partial<SettingsEditorCallbacks>;
+    blobPrefix?: string;
+    scenarioAssetPrefix?: string;
+    sharedAssetPrefix?: string;
+};
+export type RenderSettingsEditorResult = RenderResult & {
+    updateSettings: (update: Partial<Record<string, unknown>>) => Promise<void>;
+    callbacks: SettingsEditorCallbacks;
+};
+/**
+ * Renders a component wrapped in every settings editor context provider: the
+ * `setup` slot and the `scenario_editor` slot share them.
+ *
+ * `updateSettings` defaults to a no-op rather than a spy, so pass your own
+ * `vi.fn()` to assert on it.
+ *
+ * @example
+ * ```tsx
+ * const updateSettings = vi.fn();
+ * renderSettingsEditor(<App />, {
+ *   settings: { engine: { MaxPlayers: 10 } },
+ *   updateSettings,
+ * });
+ *
+ * fireEvent.change(screen.getByLabelText('Max Players'), { target: { value: '20' } });
+ * expect(updateSettings).toHaveBeenCalled();
+ * ```
+ */
+export declare function renderSettingsEditor(ui: React.ReactElement, options?: RenderSettingsEditorOptions): RenderSettingsEditorResult;
+/** The team context a session data type holds. */
+type TeamContextOf<TData> = TData extends SessionData<infer Team, object> ? Team : object;
+/**
+ * Options for {@link renderSessionUserInterface}. `TData` is the surface's
+ * generated `SessionData`, and types `sessionData` and `setData` to match.
+ */
+export type RenderSessionUserInterfaceOptions<TData extends SessionData<object, object> = SessionData<object, object>> = {
+    /** Either half may be omitted, and defaults to empty. */
+    sessionData?: Partial<TData>;
+    /** The surface's settings, keyed by settings identifier (§8). */
+    settings?: unknown;
+    /**
+     * Receives what the surface's `setData` was called with: `(teamId, update,
+     * options?)` for a team write, `(update, options?)` for a shared one.
+     */
+    setData?: SessionSetDataMock<TData>;
+    /**
+     * The key the host would send on `init` (§12.2), which `useViewerStorage`
+     * namespaces by. Defaults to a fixed test key; give two renders different
+     * keys to show their stored values stay apart.
+     */
+    sessionKey?: string;
+    theme?: SessionUserInterfaceTheme;
+    themePreference?: ThemePreference;
+    locale?: SessionUserInterfaceLocale;
+    participants?: Participant[];
+    teams?: TeamInfo[];
+    teamConfiguration?: TeamConfiguration;
+    sessionMeta?: SessionMeta;
+    teamLinks?: TeamLinks[];
+    /**
+     * Which kind of run this session surface belongs to, read by `useRunKind()`.
+     * Defaults to `'session'`.
+     */
+    runKind?: RunKind;
+    /**
+     * Where to open the walkthrough, as
+     * `useSessionUserInterfaceWalkthroughLink()` reports it. Defaults to
+     * `null`, the moment before the host has said, so a test covering the
+     * control has to supply one.
+     */
+    walkthroughLink?: WalkthroughLink | null;
+    /**
+     * Host overlays this host offers, as
+     * `useSessionUserInterfaceHostOverlays()` reports them. Defaults to none,
+     * matching a host that delegates nothing — a test covering a guide button
+     * has to say so, which is also what stops a surface accidentally passing
+     * with a control the host would never light up.
+     */
+    hostOverlays?: HostOverlay[];
+    /**
+     * Hook chains that threw, as `useSessionUserInterfaceHookFailures()` reports
+     * them. The context is required rather than defaulted, so a surface reading
+     * it throws without this provider whatever the test passes (#366).
+     */
+    hookFailures?: SessionHookFailure[];
+    /** Called by the surface's `clearFailures`; defaults to a no-op. */
+    clearHookFailures?: () => void;
+    callbacks?: Partial<SessionUserInterfaceCallbacks>;
+    blobPrefix?: string;
+    scenarioAssetPrefix?: string;
+    sharedAssetPrefix?: string;
+};
+/** What a session surface's `setData` mock receives, typed by the session data. */
+type SessionSetDataMock<TData extends SessionData<object, object>> = (teamId: string, update: ContextUpdate<TeamContextOf<TData>>, options?: SetDataOptions) => void;
+export type RenderSessionUserInterfaceResult<TData extends SessionData<object, object> = SessionData<object, object>> = RenderResult & {
+    setData: SessionSetDataMock<TData>;
+    callbacks: SessionUserInterfaceCallbacks;
+};
+/**
+ * Renders a component wrapped in all SessionUserInterface context providers.
+ *
+ * Callbacks you do not supply default to no-ops rather than spies, so pass your
+ * own `vi.fn()` for any you intend to assert on.
+ *
+ * @example
+ * ```tsx
+ * const resetGame = vi.fn();
+ * renderSessionUserInterface(<SessionDashboard />, {
+ *   sessionData: { teams: { 'team-1': createMockTeamState() } },
+ *   teams: [{ teamId: 'team-1', index: 0, name: 'Team 1' }],
+ *   callbacks: { resetGame },
+ * });
+ *
+ * fireEvent.click(screen.getByText('Reset All'));
+ * expect(resetGame).toHaveBeenCalled();
+ * ```
+ */
+export declare function renderSessionUserInterface<TData extends SessionData<object, object> = SessionData<object, object>>(ui: React.ReactElement, options?: RenderSessionUserInterfaceOptions<NoInfer<TData>>): RenderSessionUserInterfaceResult<TData>;
+export {};