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

package/dist/templates/starter-game/testing/e2e/game.spec.ts

@@ -0,0 +1,139 @@
+import { expect, test } from '@playwright/test';
+import { DEV_SERVER, getState, reinitialiseSession, runCommand } from '@seriousgaming/sdk/e2e';
+
+test.beforeEach(async () => {
+    // A session lives as long as the dev server, so start it again from the
+    // package rather than inheriting whatever the last test left behind: a
+    // reset would go back to day one but keep a team an earlier test added.
+    await reinitialiseSession();
+    // This game starts held, which is right for a real session and wrong for
+    // most of these tests: they are about the stall.
+    await runCommand({ type: 'setWaitingRoom', open: false });
+});
+
+test('a held session shows the waiting room instead of the stall', async ({ page }) => {
+    await runCommand({ type: 'setWaitingRoom', open: true });
+
+    // `?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('waiting_room'));
+    await expect(frame.getByText('Nearly opening time')).toBeVisible();
+});
+
+test('the stall opens on day one, with the whole day on one screen', async ({ page }) => {
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+    await expect(frame.getByTestId('day')).toHaveText('Day 1');
+    await expect(frame.getByText('What shall we make today?')).toBeVisible();
+    await expect(frame.getByText('How yesterday went')).toBeVisible();
+});
+
+test('changing one item leaves the others alone', async ({ page }) => {
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+
+    const lemonade = frame.getByTestId('made-lemonade');
+    const cookies = frame.getByTestId('made-cookies');
+    await expect(lemonade).toHaveText('28');
+    await expect(cookies).toHaveText('10');
+
+    await frame.getByRole('button', { name: 'Make more Lemonade' }).click();
+
+    await expect(lemonade).toHaveText('33');
+    await expect(cookies).toHaveText('10');
+});
+
+test('the stall refuses a plan bigger than it can make', async ({ page }) => {
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+
+    // Two people each changing their own item can put the merged plan over the
+    // stall's capacity, which is what the validator is for. One participant
+    // walking a single item past it reaches the same rule.
+    await runCommand({
+        type: 'updateContext',
+        teamIndex: 0,
+        payload: { plan: { Make: { lemonade: 100, icedtea: 15, cookies: 10 } } },
+    });
+    await expect(frame.getByTestId('capacity')).toHaveText('125 of 120');
+
+    // The merged plan is already over, so the next change from a surface is
+    // refused and says why.
+    await frame.getByRole('button', { name: 'Make more Cookies' }).click();
+
+    await expect(frame.getByText(/can make 120 things in a day/)).toBeVisible();
+});
+
+test('the stall opens its own day, and reports what happened', async ({ page }) => {
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+    await expect(frame.getByTestId('day')).toHaveText('Day 1');
+
+    // The players run the day, not the facilitator. In independent mode a tick
+    // requested from a player surface advances that team and nobody else.
+    await frame.getByTestId('open-stall').click();
+
+    await expect(frame.getByTestId('day')).toHaveText('Day 2');
+    await expect(frame.getByTestId('line-lemonade')).toBeVisible();
+    await expect(frame.getByTestId('day-1')).toBeVisible();
+
+    const state = (await getState()) as { session: { completedTicks: number } };
+    expect(state.session.completedTicks).toBe(1);
+
+    // A second day: day 2 is live context, and day 1 now comes back from the
+    // host's history through getPastState rather than from context.
+    await frame.getByTestId('open-stall').click();
+    await expect(frame.getByTestId('day')).toHaveText('Day 3');
+    await expect(frame.getByTestId('day-2')).toBeVisible();
+    await expect(frame.getByTestId('day-1')).toBeVisible();
+});
+
+test('one stall opening up leaves the others where they were', async ({ page }) => {
+    await runCommand({ type: 'addTeam' });
+
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+    await frame.getByTestId('open-stall').click();
+    await expect(frame.getByTestId('day')).toHaveText('Day 2');
+
+    // Asserted on the session rather than on a second browser tab: the claim is
+    // about which teams the host advanced, and reading it from the projection
+    // says so directly.
+    const state = (await getState()) as {
+        teams: { index: number; completedTicks: number }[];
+    };
+    const ticks = state.teams.map((team) => `${team.index}:${team.completedTicks}`);
+    expect(ticks[0]).toBe('0:1');
+    expect(ticks.slice(1)).not.toContain('1:1');
+});
+
+test('the stall can be switched to dark and back', async ({ page }) => {
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+
+    await frame.getByRole('button', { name: 'Dark' }).click();
+    await expect(frame.getByRole('button', { name: 'Dark' })).toHaveAttribute(
+        'aria-pressed',
+        'true'
+    );
+
+    await frame.getByRole('button', { name: 'Light' }).click();
+    await expect(frame.getByRole('button', { name: 'Light' })).toHaveAttribute(
+        'aria-pressed',
+        'true'
+    );
+});
+
+test('the facilitator can reach a stall without joining it', async ({ page }) => {
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.consoleUrl()));
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('session'));
+
+    const row = frame.getByTestId('team-team-1');
+    await expect(row.getByRole('link', { name: 'Observe' })).toHaveAttribute('target', '_blank');
+    await expect(row.getByRole('link', { name: 'Join' })).toHaveAttribute('target', '_blank');
+
+    // The facilitator watches; the stalls run their own days.
+    await expect(row.getByRole('button', { name: /Run/ })).toHaveCount(0);
+});

package/dist/templates/starter-game/testing/e2e/global-setup.ts

@@ -0,0 +1,21 @@
+import { dirname } from 'path';
+
+import type { FullConfig } from '@playwright/test';
+import { startDevServer } from '@seriousgaming/sdk-tools/client';
+
+/**
+ * Start the dev server the browser tests run against, and stop it after them.
+ *
+ * It is the server `sdk dev --isolated --port auto` runs: on free ports, with
+ * no lock file, and configured from the package alone, so it starts beside
+ * your own dev server and every run begins from the same place. Running it in
+ * this process rather than spawning `sdk dev` means stopping it is a call,
+ * which a run cannot hang on.
+ */
+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();
+}

package/dist/templates/starter-game/testing/engine/game.engine.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Whole-game tests for Lemonade Stand.
+ *
+ * These run the game in-process through `createTestSession`: no dev server, no
+ * browser, no network. The session is the one `sdk dev` runs, so a rule about
+ * how the game plays over several days belongs here, as opposed to
+ * `engine/logic.test.ts`, which is about one day's arithmetic.
+ *
+ * When a browser test fails, run these first. If they pass, the fault is in the
+ * surface or the channel to it; if they fail too, it is in the game.
+ *
+ * Run with: pnpm test:engine
+ */
+
+import { fileURLToPath } from 'url';
+
+import { createTestSession, type TestSession } from '@seriousgaming/sdk-tools/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+const PACKAGE_PATH = fileURLToPath(new URL('../..', import.meta.url));
+
+type Context = Record<string, unknown>;
+
+/** The context is untyped here, so each read says what it expects to find. */
+const cap = (context: Context, key: string) => context[key] as Record<string, unknown>;
+
+const numberField = (context: Context, key: string, field: string) =>
+    cap(context, key)[field] as number;
+
+const mapField = (context: Context, key: string, field: string) =>
+    cap(context, key)[field] as Record<string, number>;
+
+describe('Lemonade Stand', () => {
+    let game: TestSession;
+
+    beforeEach(async () => {
+        game = await createTestSession({ packagePath: PACKAGE_PATH });
+    });
+
+    afterEach(async () => {
+        await game.close();
+    });
+
+    /** The first stall's context, which these tests play. */
+    const stall = (): Context => {
+        const team = game.state().teams.find((candidate) => candidate.index === 0);
+        if (!team) throw new Error('The session has no first stall');
+        return team.context;
+    };
+
+    const day = () => game.state().session.completedTicks;
+
+    /** Open the stall for a day, and fail loudly if the session refused. */
+    const tick = async (): Promise<Context> => {
+        const result = await game.send({ type: 'tick' });
+        if (!result.ok) throw new Error(`The day was refused: ${JSON.stringify(result.outcome)}`);
+        return stall();
+    };
+
+    /** Decide what to make, as the stall's own surface would write it. */
+    const make = async (counts: Record<string, number>) => {
+        const result = await game.send({
+            type: 'updateContext',
+            teamIndex: 0,
+            payload: { plan: { Make: counts } },
+        });
+        expect(result.ok).toBe(true);
+    };
+
+    const lines = (context: Context) =>
+        cap(context, 'results').Lines as Record<string, Record<string, number>>;
+
+    it('starts every item on the menu at a number the stall can make', () => {
+        const plan = mapField(stall(), 'plan', 'Make');
+
+        expect(Object.keys(plan).sort()).toEqual(['cookies', 'icedtea', 'lemonade']);
+        expect(Object.values(plan).reduce((sum, count) => sum + count, 0)).toBeLessThanOrEqual(120);
+    });
+
+    it('opens with nothing traded and a forecast for the first day', () => {
+        expect(day()).toBe(0);
+        expect(numberField(stall(), 'results', 'Day')).toBe(0);
+        expect(['sunny', 'cloudy', 'rainy']).toContain(cap(stall(), 'weather').Today);
+    });
+
+    it('sells what it made, and turns the rest away', async () => {
+        await make({ lemonade: 1, icedtea: 0, cookies: 0 });
+        const context = await tick();
+
+        expect(lines(context).lemonade!.Sold).toBe(1);
+        expect(lines(context).lemonade!.PouredAway).toBe(0);
+        expect(lines(context).lemonade!.TurnedAway).toBeGreaterThan(0);
+    });
+
+    it('pours away what nobody wanted, having already paid for it', async () => {
+        await make({ lemonade: 0, icedtea: 0, cookies: 100 });
+        const context = await tick();
+
+        expect(lines(context).cookies!.PouredAway).toBeGreaterThan(0);
+        // 100 cookies at 25p, whatever the day did.
+        expect(numberField(context, 'results', 'Spent')).toBe(100 * 25);
+        expect(numberField(context, 'results', 'Profit')).toBeLessThan(0);
+    });
+
+    it('makes more money matching the forecast than ignoring it', async () => {
+        await make(mapField(stall(), 'weather', 'Expected'));
+        for (let round = 0; round < 5; round += 1) await tick();
+        const matched = numberField(stall(), 'results', 'Purse');
+
+        expect((await game.send({ type: 'reinitialise' })).ok).toBe(true);
+        await make({ lemonade: 0, icedtea: 0, cookies: 0 });
+        for (let round = 0; round < 5; round += 1) await tick();
+        const nothing = numberField(stall(), 'results', 'Purse');
+
+        expect(matched).toBeGreaterThan(nothing);
+    });
+
+    it('keeps a running purse across days', async () => {
+        await make(mapField(stall(), 'weather', 'Expected'));
+
+        const first = await tick();
+        const second = await tick();
+
+        expect(numberField(second, 'results', 'Purse')).toBe(
+            numberField(first, 'results', 'Profit') + numberField(second, 'results', 'Profit')
+        );
+    });
+
+    it('labels each day with its own number', async () => {
+        await tick();
+        await tick();
+        await tick();
+
+        expect(numberField(stall(), 'results', 'Day')).toBe(3);
+    });
+
+    it('plays the day it forecast, not a different one', async () => {
+        const forecastForDayOne = cap(stall(), 'weather').Today;
+
+        const context = await tick();
+
+        expect(cap(context, 'results').Weather).toBe(forecastForDayOne);
+        // And it has moved on to forecasting day two.
+        expect(['sunny', 'cloudy', 'rainy']).toContain(cap(context, 'weather').Today);
+    });
+
+    it('leaves the plan alone, so yesterday carries into today', async () => {
+        await make({ lemonade: 44, icedtea: 0, cookies: 0 });
+        const context = await tick();
+
+        expect(cap(context, 'plan').Make).toEqual({ lemonade: 44, icedtea: 0, cookies: 0 });
+    });
+
+    it('trades its ten days', async () => {
+        for (let round = 0; round < 10; round += 1) await tick();
+
+        expect(day()).toBe(10);
+        expect(numberField(stall(), 'results', 'Day')).toBe(10);
+    });
+
+    it('undo takes back the last day', async () => {
+        await tick();
+        expect(day()).toBe(1);
+
+        expect((await game.send({ type: 'undo' })).ok).toBe(true);
+
+        expect(day()).toBe(0);
+        expect(numberField(stall(), 'results', 'Purse')).toBe(0);
+        expect(numberField(stall(), 'results', 'Day')).toBe(0);
+    });
+});

package/dist/templates/starter-game/tsconfig.json

@@ -0,0 +1,19 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "esnext",
+        "allowJs": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "noImplicitAny": true,
+        "sourceMap": true,
+        "noEmit": true,
+        "moduleResolution": "bundler",
+        "noUncheckedSideEffectImports": false,
+        "resolveJsonModule": true,
+        "jsx": "react-jsx",
+        "paths": {
+            "@seriousgaming/sdk": ["../../sdk"]
+        }
+    }
+}

package/dist/templates/starter-game/ui/defaults.ts

@@ -0,0 +1,60 @@
+// This file is auto-generated from the schemas the resource declares: the values
+// a session starts with, for use as test fixtures.
+// Do not edit this file directly. It will be regenerated on build.
+
+import type { Context, Settings } from './types';
+
+export const defaultContext: Context = {
+    plan: {
+        Make: {},
+    },
+    weather: {
+        Today: 'sunny',
+        Expected: {},
+    },
+    results: {
+        Day: 0,
+        Weather: 'sunny',
+        Lines: {},
+        Takings: 0,
+        Spent: 0,
+        Profit: 0,
+        Purse: 0,
+    },
+    roles: {
+        LooksAfter: {},
+    },
+    briefing: {
+        Message: '',
+    },
+};
+
+export const defaultSettings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: {
+                Name: 'Lemonade',
+                Order: 1,
+                Cost: 15,
+                Price: 50,
+            },
+            icedtea: {
+                Name: 'Iced tea',
+                Order: 2,
+                Cost: 20,
+                Price: 60,
+            },
+            cookies: {
+                Name: 'Cookies',
+                Order: 3,
+                Cost: 25,
+                Price: 70,
+            },
+        },
+    },
+    ui: {
+        Step: 5,
+        CurrencySymbol: '£',
+    },
+};

package/dist/templates/starter-game/ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Lemonade Stand</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="./src/main.tsx"></script>
+    </body>
+</html>

package/dist/templates/starter-game/ui/src/App.test.tsx

@@ -0,0 +1,138 @@
+import { createMockParticipant, renderUserInterface } from '@seriousgaming/sdk/ui/testing';
+import { fireEvent, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import App from './App';
+import './i18n';
+import { baseSettings, baseContext, playedDay } from './test-helpers';
+
+const ada = createMockParticipant({ id: 'participant-1', name: 'Ada' });
+
+const render = (options: Parameters<typeof renderUserInterface>[1] = {}) =>
+    renderUserInterface(<App />, {
+        data: baseContext,
+        settings: baseSettings,
+        participant: ada,
+        ...options,
+    });
+
+describe('the screen', () => {
+    // One screen, top to bottom: what we are making, how yesterday went, every
+    // day so far. No tabs, because there is nothing here worth hiding behind one.
+    it('shows today, yesterday and the days before it at once', () => {
+        render({ data: playedDay });
+
+        expect(screen.getByText('What shall we make today?')).toBeInTheDocument();
+        expect(screen.getByText('How yesterday went')).toBeInTheDocument();
+        expect(screen.getByText('Every day so far')).toBeInTheDocument();
+    });
+
+    it('leaves the history out until there is any', () => {
+        render();
+
+        expect(screen.queryByText('Every day so far')).not.toBeInTheDocument();
+    });
+
+    it('counts the day the stall is about to trade, not the one it finished', () => {
+        render({ completedTicks: 3 });
+
+        expect(screen.getByTestId('day')).toHaveTextContent('Day 4');
+    });
+
+    it('says what the weather is doing', () => {
+        render();
+
+        expect(screen.getByText(/Sunny today/)).toBeInTheDocument();
+    });
+
+    it('says who looks after what', () => {
+        render({
+            data: { ...baseContext, roles: { LooksAfter: { 'participant-1': 'icedtea' } } },
+        });
+
+        expect(screen.getByText('You look after the Iced tea')).toBeInTheDocument();
+    });
+
+    it('says when a day is being played out', () => {
+        render({ isRoundProcessing: true });
+
+        expect(screen.getByText('The day is being played out')).toBeInTheDocument();
+    });
+
+    it('carries the facilitator’s notice', () => {
+        render({ data: { ...baseContext, briefing: { Message: 'Ten minutes left' } } });
+
+        expect(screen.getByText('Ten minutes left')).toBeInTheDocument();
+    });
+});
+
+describe('yesterday', () => {
+    it('waits for the first day rather than showing zeroes', () => {
+        render();
+
+        expect(
+            screen.getByText(/the stall opens when the facilitator says so/)
+        ).toBeInTheDocument();
+    });
+
+    it('reports what was poured away and who was turned away', () => {
+        render({ data: playedDay });
+
+        // Five iced teas made and poured away; forty-two people who wanted
+        // something and did not get it. The two mistakes look nothing alike and
+        // cost differently, so the screen names them separately.
+        expect(screen.getByTestId('stat-pouredaway')).toHaveTextContent('5');
+        expect(screen.getByTestId('stat-turnedaway')).toHaveTextContent('42');
+        expect(screen.getByTestId('stat-profit')).toHaveTextContent('£23.50');
+    });
+});
+
+describe('light and dark', () => {
+    it('asks the host, so the whole session follows rather than one frame', () => {
+        const setThemePreference = vi.fn();
+        render({ themePreference: 'light', callbacks: { setThemePreference } });
+
+        fireEvent.click(screen.getByRole('button', { name: 'Dark' }));
+
+        expect(setThemePreference).toHaveBeenCalledWith('dark');
+    });
+
+    it('shows which one is on', () => {
+        render({ themePreference: 'dark' });
+
+        expect(screen.getByRole('button', { name: 'Dark' })).toHaveAttribute(
+            'aria-pressed',
+            'true'
+        );
+    });
+
+    it('does not leave the control in no state at all', () => {
+        const setThemePreference = vi.fn();
+        render({ themePreference: 'dark', callbacks: { setThemePreference } });
+
+        // Pressing the one already selected hands MUI a null value.
+        fireEvent.click(screen.getByRole('button', { name: 'Dark' }));
+
+        expect(setThemePreference).not.toHaveBeenCalled();
+    });
+});
+
+describe('when a write is refused', () => {
+    /**
+     * A validator refusal arrives twice: as a mutation outcome, and through the
+     * rejection channel, which carries the validator's own message. Only the
+     * second is worth showing, and this is what holds that choice in place.
+     */
+    it('shows the validator’s own reason', () => {
+        render({
+            validationRejections: [
+                {
+                    validatorIdentifier: 'capacity',
+                    message: 'The stall can make 120 things in a day, and that plan asks for 150.',
+                },
+            ],
+        });
+
+        expect(screen.getByText(/that plan asks for 150/)).toBeInTheDocument();
+    });
+});