game-harness 1.0.0

package/dist/esm/bin/visual-battery.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { runVisualBattery, VisualBatteryError } from '../visual-battery.js';
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: game-harness-visual-battery [harness-directory] [--ci]
+
+Runs the configured Vitest browser harness and fails when committed screenshot
+baselines drift. --ci also refuses to start from a dirty baseline directory.
+
+Arguments:
+  harness-directory  Directory containing *.browser.test.ts(x) files
+                     (default: tests/harness)
+
+Options:
+  --ci                Fail on drift and refuse a dirty starting state
+  -h, --help          Show this help
+
+The legacy executable name test-harness-visual-battery remains available.`);
+    process.exit(0);
+}
+const unknownFlags = args.filter((argument) => argument.startsWith('-') && argument !== '--ci');
+if (unknownFlags.length > 0) {
+    console.error(`Unknown option(s): ${unknownFlags.join(', ')}. Use --help for usage.`);
+    process.exit(2);
+}
+const positionalArgs = args.filter((argument) => !argument.startsWith('-'));
+if (positionalArgs.length > 1) {
+    console.error('Expected at most one harness-directory. Use --help for usage.');
+    process.exit(2);
+}
+const ci = args.includes('--ci');
+const harnessDirArg = positionalArgs[0] ?? 'tests/harness';
+try {
+    runVisualBattery(harnessDirArg, { ci });
+}
+catch (err) {
+    if (err instanceof VisualBatteryError) {
+        process.exit(1);
+    }
+    throw err;
+}

package/dist/esm/browser-config.js

@@ -0,0 +1,80 @@
+import { playwright } from '@vitest/browser-playwright';
+import { createChromiumLaunchProfile } from './chromium-launch.js';
+function resolveHeadless(headless) {
+    if (typeof headless === 'boolean')
+        return headless;
+    // Explicit legacy/hosted-runner mode: headed locally, headless under CI.
+    return Boolean(process.env.CI);
+}
+/**
+ * Builds a `test` fragment for a Vitest Browser Mode project, wired for
+ * real-Chromium (or other Playwright-driven browser) test execution.
+ *
+ * Encodes a reviewed pattern: headed by default both locally and in
+ * CI, silent at the Chromium boundary, and native renderer selection unless a
+ * consumer explicitly requests software or the proven Linux Vulkan profile.
+ *
+ * The returned object is meant to be spread into a Vitest `projects[]`
+ * entry's `test` field (or merged into a top-level `test` block for
+ * single-project setups):
+ *
+ * ```ts
+ * import { defineBrowserTestConfig } from 'game-harness/vitest';
+ *
+ * export default defineConfig({
+ *   test: {
+ *     projects: [
+ *       { extends: true, test: { name: 'unit', environment: 'node', include: [...] } },
+ *       { extends: true, test: defineBrowserTestConfig({
+ *           optimizeDeps: ['three/examples/jsm/utils/SkeletonUtils.js'],
+ *         }) },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * NOTE: a headed browser needs a display server. On Linux CI images without
+ * one, wrap the test command in `xvfb-run` rather than forcing headless here.
+ */
+export function defineBrowserTestConfig(opts = {}) {
+    const { contextOptions = {}, gpuArgs = [], gpuMode = 'auto', headless = false, ui = false, instances = [{ browser: 'chromium' }], optimizeDeps = [], setupFiles, name = 'browser', include = ['tests/browser/**/*.browser.test.{ts,tsx}'], fileParallelism = false, } = opts;
+    if (!name.trim())
+        throw new TypeError('browser project name must not be empty');
+    if (instances.length === 0) {
+        throw new TypeError('browser instances must contain at least one Playwright browser');
+    }
+    if (include.length === 0 || include.some((pattern) => !pattern.trim())) {
+        throw new TypeError('browser include must contain at least one non-empty test glob');
+    }
+    const resolvedHeadless = resolveHeadless(headless);
+    const launchProfile = createChromiumLaunchProfile({ gpuMode, args: gpuArgs });
+    if (ui && contextOptions.deviceScaleFactor !== undefined) {
+        throw new Error('Vitest browser UI uses a null viewport, so contextOptions.deviceScaleFactor is not supported when ui is true');
+    }
+    const resolvedContextOptions = ui ? contextOptions : { deviceScaleFactor: 1, ...contextOptions };
+    const test = {
+        name,
+        include,
+        fileParallelism,
+        browser: {
+            enabled: true,
+            headless: resolvedHeadless,
+            ui,
+            provider: playwright({
+                launchOptions: launchProfile,
+                contextOptions: resolvedContextOptions,
+            }),
+            instances,
+        },
+    };
+    if (setupFiles) {
+        test.setupFiles = [...setupFiles];
+    }
+    if (optimizeDeps.length > 0) {
+        // Vitest's `test` fragment has no `optimizeDeps` field (that lives at
+        // the top-level Vite config) — surface the caller's list here so a
+        // single options object can drive both without duplicating it.
+        test.__optimizeDepsInclude = [...new Set(optimizeDeps)];
+    }
+    return test;
+}

package/dist/esm/chromium-launch.js

@@ -0,0 +1,34 @@
+const GPU_ARGS = {
+    auto: [],
+    software: ['--use-gl=swiftshader', '--enable-webgl', '--ignore-gpu-blocklist'],
+    'linux-hardware-vulkan': [
+        '--use-gpu-in-tests',
+        '--use-gl=angle',
+        '--use-angle=vulkan',
+        '--ignore-gpu-blocklist',
+    ],
+};
+/**
+ * Builds the shared Chromium renderer and silence profile without deciding
+ * whether the browser is headed. Callers own that explicit choice.
+ */
+export function createChromiumLaunchProfile(options = {}) {
+    const gpuMode = options.gpuMode ?? 'auto';
+    const args = [
+        ...new Set([...GPU_ARGS[gpuMode], ...(options.args ?? [])].filter((argument) => argument !== '--mute-audio')),
+        '--mute-audio',
+    ];
+    if (gpuMode === 'linux-hardware-vulkan') {
+        return {
+            args,
+            env: {
+                ...process.env,
+                ...options.env,
+                EGL_PLATFORM: options.env?.EGL_PLATFORM ?? 'surfaceless',
+            },
+        };
+    }
+    if (options.env)
+        return { args, env: { ...process.env, ...options.env } };
+    return { args };
+}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { lighthouseAssertions, } from './lighthouse.js';
+export { verifyReleaseLadder, } from './release-ladder.js';
+export { runVisualBattery, VisualBatteryError, } from './visual-battery.js';

package/dist/esm/lighthouse.js

@@ -0,0 +1,70 @@
+const PRESETS = {
+    // A production lighthouserc.json, verbatim: perf 0.6 / a11y 0.85 /
+    // best-practices 0.7 (warn-level, not error — a score dip surfaces in CI
+    // logs without hard-blocking a merge on Lighthouse's inherent run-to-run
+    // variance), SEO/PWA assertions off since these are single-page game
+    // shells with no SEO surface and no installable-PWA requirement.
+    'game-default': {
+        ci: {
+            collect: {
+                staticDistDir: './dist',
+                url: ['http://localhost/index.html'],
+                numberOfRuns: 3,
+                settings: {
+                    preset: 'desktop',
+                    chromeFlags: '--no-sandbox --disable-dev-shm-usage --disable-gpu',
+                },
+            },
+            assert: {
+                preset: 'lighthouse:no-pwa',
+                assertions: {
+                    'categories:performance': ['warn', { minScore: 0.6 }],
+                    'categories:accessibility': ['warn', { minScore: 0.85 }],
+                    'categories:best-practices': ['warn', { minScore: 0.7 }],
+                    'categories:seo': 'off',
+                    'uses-responsive-images': 'off',
+                    'uses-rel-preconnect': 'off',
+                    'csp-xss': 'off',
+                },
+            },
+            upload: { target: 'temporary-public-storage' },
+        },
+    },
+};
+export function lighthouseAssertions(preset = 'game-default', overrides = {}) {
+    const base = PRESETS[preset];
+    if (!base) {
+        throw new Error(`unknown lighthouse preset: ${preset}. known presets: ${Object.keys(PRESETS).join(', ')}`);
+    }
+    const staticDistDir = overrides.staticDistDir ?? base.ci.collect.staticDistDir;
+    if (staticDistDir !== undefined && !staticDistDir.trim()) {
+        throw new TypeError('Lighthouse staticDistDir must not be empty');
+    }
+    const url = overrides.url ?? base.ci.collect.url;
+    if (url.length === 0 || url.some((entry) => !entry.trim())) {
+        throw new TypeError('Lighthouse url must contain at least one non-empty URL');
+    }
+    const numberOfRuns = overrides.numberOfRuns ?? base.ci.collect.numberOfRuns;
+    if (!Number.isInteger(numberOfRuns) || numberOfRuns < 1) {
+        throw new TypeError('Lighthouse numberOfRuns must be a positive integer');
+    }
+    return {
+        ci: {
+            collect: {
+                ...base.ci.collect,
+                staticDistDir,
+                url: [...url],
+                numberOfRuns,
+                settings: { ...base.ci.collect.settings },
+            },
+            assert: {
+                ...base.ci.assert,
+                assertions: structuredClone({
+                    ...base.ci.assert.assertions,
+                    ...overrides.assertions,
+                }),
+            },
+            upload: { ...base.ci.upload },
+        },
+    };
+}

package/dist/esm/playwright-config.js

@@ -0,0 +1,292 @@
+import { defineConfig, devices, expect, } from '@playwright/test';
+import { createChromiumLaunchProfile } from './chromium-launch.js';
+import { SILENT_QA_MARKER_ATTRIBUTE, SILENT_QA_MARKER_VALUE, SILENT_QA_QUERY_PARAMETER, SILENT_QA_QUERY_VALUE, } from './silent-qa.js';
+export { SILENT_QA_MARKER_ATTRIBUTE, SILENT_QA_MARKER_VALUE, SILENT_QA_QUERY_PARAMETER, SILENT_QA_QUERY_VALUE, } from './silent-qa.js';
+/**
+ * Adds a non-persistent mute mode to a relative or absolute URL.
+ * Explicit caller parameters replace existing values, and the mute value is
+ * applied last so a stale `muted=0` can never make an agent run audible.
+ */
+export function silentTestUrl(target = '.', parameters = {}, options = {}) {
+    const fragmentIndex = target.indexOf('#');
+    const fragment = fragmentIndex >= 0 ? target.slice(fragmentIndex) : '';
+    const withoutFragment = fragmentIndex >= 0 ? target.slice(0, fragmentIndex) : target;
+    const queryIndex = withoutFragment.indexOf('?');
+    const pathname = queryIndex >= 0 ? withoutFragment.slice(0, queryIndex) : withoutFragment;
+    const query = queryIndex >= 0 ? withoutFragment.slice(queryIndex + 1) : '';
+    const search = new URLSearchParams(query);
+    for (const [key, value] of Object.entries(parameters))
+        search.set(key, String(value));
+    search.set(options.muteQueryParameter ?? SILENT_QA_QUERY_PARAMETER, options.muteQueryValue ?? SILENT_QA_QUERY_VALUE);
+    return `${pathname}?${search.toString()}${fragment}`;
+}
+/**
+ * Navigates to a game in runtime-only mute mode and fails closed until the
+ * application confirms that audio was muted before test interaction begins.
+ */
+export async function openSilentGame(page, target = '.', parameters = {}, options = {}) {
+    const response = await page.goto(silentTestUrl(target, parameters, {
+        ...(options.muteQueryParameter === undefined
+            ? {}
+            : { muteQueryParameter: options.muteQueryParameter }),
+        ...(options.muteQueryValue === undefined ? {} : { muteQueryValue: options.muteQueryValue }),
+    }), options.navigationOptions);
+    await expect(page.locator(options.markerSelector ?? 'html')).toHaveAttribute(options.markerAttribute ?? SILENT_QA_MARKER_ATTRIBUTE, options.markerValue ?? SILENT_QA_MARKER_VALUE, { timeout: options.markerTimeout ?? 5_000 });
+    return response;
+}
+function mergeMutedLaunchOptions(...sources) {
+    const merged = Object.assign({}, ...sources.filter((source) => source !== undefined));
+    const args = sources
+        .flatMap((source) => source?.args ?? [])
+        .filter((argument) => argument !== '--mute-audio');
+    return { ...merged, args: [...new Set(args), '--mute-audio'] };
+}
+const DEVICE_TIER_PROJECTS = {
+    desktop: [
+        {
+            name: 'desktop',
+            use: {
+                ...devices['Desktop Chrome'],
+                viewport: { width: 1280, height: 720 },
+            },
+        },
+    ],
+    mobile: [{ name: 'mobile', use: { ...devices['Pixel 7'] } }],
+    tablet: [{ name: 'tablet', use: { ...devices['iPad Mini'] } }],
+    // The foldable form factor sits between tablet and phone — wide CSS-px
+    // viewport but Android UA, touch primary, high DPR. Portrait + landscape
+    // are separate projects since HUD layout regressions differ by axis.
+    foldable: [
+        {
+            name: 'foldable-portrait',
+            use: {
+                ...devices['Pixel 7'],
+                viewport: { width: 840, height: 2120 },
+                deviceScaleFactor: 3,
+            },
+        },
+        {
+            name: 'foldable-landscape',
+            use: {
+                ...devices['Pixel 7'],
+                viewport: { width: 2120, height: 840 },
+                deviceScaleFactor: 3,
+            },
+        },
+    ],
+    ultrawide: [
+        {
+            name: 'ultrawide',
+            use: {
+                ...devices['Desktop Chrome'],
+                viewport: { width: 3440, height: 1440 },
+            },
+        },
+    ],
+};
+const DEFAULT_PORT = 4173;
+const CI_PORT_START = 20_000;
+const CI_PORT_SPAN = 10_000;
+const LOCAL_TEST_TIMEOUT_MS = 45_000;
+const LOCAL_ACTION_TIMEOUT_MS = 15_000;
+const LOCAL_NAV_TIMEOUT_MS = 15_000;
+function validPort(value) {
+    return Number.isInteger(value) && value > 0 && value <= 65_535;
+}
+function stableHash(value) {
+    let hash = 2_166_136_261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    return hash >>> 0;
+}
+function normalizePlaywrightChildEnvironment() {
+    // Playwright 1.62 injects FORCE_COLOR=1 into web-server and worker
+    // processes. An inherited NO_COLOR is therefore ignored and only makes
+    // Node emit a warning in each child. Removing it here changes this
+    // Playwright subprocess only; the invoking shell remains untouched.
+    delete process.env.NO_COLOR;
+}
+/**
+ * Resolves one stable Playwright preview port for every config reload in an
+ * Actions job. Explicit `PLAYWRIGHT_PORT`/`PW_PORT` values win; local runs use
+ * `localPort`; GitHub/Gitea CI hashes repository, run, job, and local port into
+ * an isolated port range.
+ */
+export function resolvePlaywrightPort(options = {}) {
+    const environment = options.environment ?? process.env;
+    const configuredValue = environment.PLAYWRIGHT_PORT ?? environment.PW_PORT;
+    if (configuredValue !== undefined) {
+        const configuredPort = Number(configuredValue);
+        if (!validPort(configuredPort)) {
+            throw new TypeError(`PLAYWRIGHT_PORT/PW_PORT must be an integer from 1 to 65535; received ${configuredValue || '<empty>'}`);
+        }
+        return configuredPort;
+    }
+    const localPort = options.localPort ?? DEFAULT_PORT;
+    if (!validPort(localPort)) {
+        throw new TypeError(`Playwright port must be an integer from 1 to 65535; received ${localPort}`);
+    }
+    const runId = environment.GITHUB_RUN_ID ?? environment.GITHUB_RUN_NUMBER;
+    if (!environment.CI || !runId)
+        return localPort;
+    const identity = [
+        environment.GITHUB_REPOSITORY ?? '',
+        runId,
+        environment.GITHUB_JOB ?? '',
+        String(localPort),
+    ].join('\0');
+    return CI_PORT_START + (stableHash(identity) % CI_PORT_SPAN);
+}
+function normalizeBasePath(basePath) {
+    const trimmed = basePath.trim();
+    if (!trimmed || trimmed === '/')
+        return '/';
+    if (trimmed.includes('?') || trimmed.includes('#')) {
+        throw new TypeError(`Playwright basePath must be a pathname without a query or fragment; received ${basePath}`);
+    }
+    const segments = trimmed
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            throw new TypeError(`Playwright basePath contains invalid URL encoding; received ${basePath}`);
+        }
+    });
+    if (segments.some((segment) => segment === '.' || segment === '..' || /[\\/]/u.test(segment))) {
+        throw new TypeError(`Playwright basePath must not contain traversal or encoded separators; received ${basePath}`);
+    }
+    return segments.length === 0 ? '/' : `/${segments.join('/')}/`;
+}
+/**
+ * Builds a full Playwright config, encoding a tiered-device +
+ * env-gated-suite convention:
+ *
+ * - `desktop` project always runs; `MULTIVIEW=1` (or `VISUAL=1`) expands to
+ *   every requested device tier (mobile/tablet/foldable/ultrawide).
+ * - `JOURNEY=1` (or `VISUAL=1`) opts into expensive artefact-producing specs
+ *   that are excluded from the default tier-1 functional gate so CI stays
+ *   fast.
+ * - `VISUAL=1` additionally adds `visualSpecs` to the test match glob.
+ * - CI timeouts scale up from local defaults via `ciTimeoutMultiplier`
+ *   (CI runners run WebGL/render-heavy tests 2-4x slower than local dev).
+ */
+export function definePlaywrightConfig(opts = {}) {
+    normalizePlaywrightChildEnvironment();
+    const { testDir = './tests', basePath = '/', port, webServerCommand, gpuMode = 'auto', headless = false, deviceTiers = ['desktop'], extraProjects = [], journeySpecs = [], ciTimeoutMultiplier = 4, overrides = {}, } = opts;
+    const IS_CI = Boolean(process.env.CI);
+    const IS_HEADLESS = process.env.PW_HEADLESS === '1' || (headless === 'ci-only' ? IS_CI : headless);
+    const CHROMIUM_CHANNEL = process.env.PW_CHROMIUM_CHANNEL ?? (!IS_CI && !IS_HEADLESS ? 'chrome' : undefined);
+    if (!Number.isFinite(ciTimeoutMultiplier) || ciTimeoutMultiplier <= 0) {
+        throw new TypeError('ciTimeoutMultiplier must be a positive finite number');
+    }
+    if (deviceTiers.length === 0) {
+        throw new TypeError('deviceTiers must contain at least one tier');
+    }
+    const unknownTiers = deviceTiers.filter((tier) => !Object.hasOwn(DEVICE_TIER_PROJECTS, tier));
+    if (unknownTiers.length > 0) {
+        throw new TypeError(`unknown device tier(s): ${unknownTiers.join(', ')}`);
+    }
+    const PORT = resolvePlaywrightPort({ localPort: port ?? DEFAULT_PORT });
+    const BASE_URL = `http://127.0.0.1:${PORT}${normalizeBasePath(basePath)}`;
+    const REUSE_SERVER = !IS_CI && process.env.PW_REUSE_SERVER === '1';
+    const includeVisual = process.env.VISUAL === '1';
+    const includeMultiview = process.env.MULTIVIEW === '1' || includeVisual;
+    const includeJourney = process.env.JOURNEY === '1' || includeVisual;
+    // Specs live under e2e/ (+ visual/ when VISUAL=1) relative to testDir.
+    const testMatch = includeVisual
+        ? ['e2e/**/*.spec.ts', 'visual/**/*.spec.ts']
+        : 'e2e/**/*.spec.ts';
+    const testIgnore = includeJourney ? [] : journeySpecs;
+    const TEST_TIMEOUT_MS = IS_CI
+        ? LOCAL_TEST_TIMEOUT_MS * ciTimeoutMultiplier
+        : LOCAL_TEST_TIMEOUT_MS;
+    const ACTION_TIMEOUT_MS = IS_CI
+        ? LOCAL_ACTION_TIMEOUT_MS * ciTimeoutMultiplier
+        : LOCAL_ACTION_TIMEOUT_MS;
+    const NAV_TIMEOUT_MS = IS_CI ? LOCAL_NAV_TIMEOUT_MS * 2 : LOCAL_NAV_TIMEOUT_MS;
+    const uniqueDeviceTiers = [...new Set(deviceTiers)];
+    const tiers = includeMultiview
+        ? uniqueDeviceTiers
+        : uniqueDeviceTiers.slice(0, 1);
+    // `DEVICE_TIER_PROJECTS` is typed `Record<DeviceTier, Project[]>`, so every
+    // member of the closed `DeviceTier` union is guaranteed present — this
+    // fallback only guards a future widening of the type, and is unreachable
+    // through any call this factory's own (type-checked) public API permits.
+    /* v8 ignore next */
+    const tierProjects = tiers.flatMap((tier) => DEVICE_TIER_PROJECTS[tier] ?? []);
+    const projects = [...tierProjects, ...extraProjects];
+    const launchProfile = createChromiumLaunchProfile({ gpuMode });
+    const base = {
+        testDir,
+        testMatch,
+        testIgnore,
+        fullyParallel: true,
+        forbidOnly: IS_CI,
+        retries: IS_CI ? 2 : 0,
+        reporter: IS_CI ? 'github' : 'list',
+        timeout: TEST_TIMEOUT_MS,
+        use: {
+            baseURL: BASE_URL,
+            headless: IS_HEADLESS,
+            trace: 'retain-on-failure',
+            actionTimeout: ACTION_TIMEOUT_MS,
+            navigationTimeout: NAV_TIMEOUT_MS,
+            browserName: 'chromium',
+            channel: CHROMIUM_CHANNEL,
+            launchOptions: mergeMutedLaunchOptions(launchProfile),
+        },
+        webServer: {
+            command: webServerCommand?.(PORT) ?? `pnpm exec vite --host 127.0.0.1 --port ${PORT} --strictPort`,
+            url: BASE_URL,
+            reuseExistingServer: REUSE_SERVER,
+            timeout: 60_000,
+        },
+        projects,
+    };
+    const resolved = defineConfig(base);
+    // `base.webServer` above is always constructed as a single object literal,
+    // and Playwright's own `defineConfig` never turns a single `webServer`
+    // into an array — this branch only guards a future Playwright type
+    // widening and is unreachable through this factory's own construction.
+    /* v8 ignore next */
+    const singleWebServer = Array.isArray(resolved.webServer) ? undefined : resolved.webServer;
+    /* v8 ignore next 5 */
+    const mergedWebServer = Array.isArray(resolved.webServer)
+        ? resolved.webServer
+        : { ...singleWebServer, ...overrides.webServer };
+    const mergedUse = {
+        ...resolved.use,
+        ...overrides.use,
+        launchOptions: mergeMutedLaunchOptions(resolved.use?.launchOptions, overrides.use?.launchOptions),
+    };
+    // `base.projects` above is always populated (from `projects` computed
+    // earlier), so `resolved.projects` is never nullish and this final `[]`
+    // only guards a hypothetical future Playwright `defineConfig` behavior —
+    // unreachable through this factory's own construction.
+    /* v8 ignore next */
+    const configuredProjects = overrides.projects ?? resolved.projects ?? [];
+    const mutedProjects = configuredProjects.map((project) => ({
+        ...project,
+        use: {
+            ...project.use,
+            launchOptions: mergeMutedLaunchOptions(mergedUse.launchOptions, project.use?.launchOptions),
+        },
+    }));
+    return {
+        ...resolved,
+        ...overrides,
+        // `use` and `webServer` are merged one level deep — a caller supplying
+        // `overrides.use` almost always wants to ADD a field (e.g. `channel` or
+        // an extra header), not replace baseURL/headless/timeouts wholesale.
+        // Every other top-level field (projects, testMatch, etc.) still fully
+        // replaces on override, matching a plain object spread.
+        use: mergedUse,
+        webServer: mergedWebServer,
+        projects: mutedProjects,
+    };
+}