game-harness 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes are recorded here. Releases follow
 [Semantic Versioning](https://semver.org/) and are generated from Conventional
 Commits by release-please.
 
+## [1.2.0](https://github.com/jbcom/game-harness/compare/game-harness-v1.1.2...game-harness-v1.2.0) (2026-10-10)
+
+
+### Features
+
+* **vitest:** pass the browser server's api, custom commands, failure screenshots and isolation through ([29c6d2d](https://github.com/jbcom/game-harness/commit/29c6d2dbaf099b7dcdf8a9cd2b1ffa621e9d9059))
+
 ## [1.1.2](https://github.com/jbcom/game-harness/compare/game-harness-v1.1.1...game-harness-v1.1.2) (2026-10-07)
 
 

package/dist/cjs/browser-config.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineBrowserTestConfig = defineBrowserTestConfig;
 const browser_playwright_1 = require("@vitest/browser-playwright");
 const chromium_launch_js_1 = require("./chromium-launch.js");
+const vitest_major_js_1 = require("./vitest-major.js");
 function resolveHeadless(headless) {
     if (typeof headless === 'boolean')
         return headless;
@@ -40,7 +41,7 @@ function resolveHeadless(headless) {
  * one, wrap the test command in `xvfb-run` rather than forcing headless here.
  */
 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;
+    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, api, commands, screenshotFailures, isolate, } = opts;
     if (!name.trim())
         throw new TypeError('browser project name must not be empty');
     if (instances.length === 0) {
@@ -73,6 +74,19 @@ function defineBrowserTestConfig(opts = {}) {
     if (setupFiles) {
         test.setupFiles = [...setupFiles];
     }
+    if (api) {
+        if ((0, vitest_major_js_1.vitestMajor)() >= 5)
+            test.api = { ...api };
+        // Vitest 4's browser server reads its own `api`; Vitest 5's types no longer carry it.
+        else
+            test.browser.api = { ...api };
+    }
+    if (commands)
+        test.browser = { ...test.browser, commands: { ...commands } };
+    if (screenshotFailures !== undefined)
+        test.browser = { ...test.browser, screenshotFailures };
+    if (isolate !== undefined)
+        test.isolate = isolate;
     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

package/dist/cjs/vitest-major.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vitestMajor = vitestMajor;
+const node_1 = require("vitest/node");
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+function vitestMajor() {
+    const major = Number.parseInt(node_1.version, 10);
+    if (!Number.isFinite(major))
+        throw new Error(`unrecognised Vitest version: ${node_1.version}`);
+    return major;
+}

package/dist/esm/browser-config.js

@@ -1,5 +1,6 @@
 import { playwright } from '@vitest/browser-playwright';
 import { createChromiumLaunchProfile } from './chromium-launch.js';
+import { vitestMajor } from './vitest-major.js';
 function resolveHeadless(headless) {
     if (typeof headless === 'boolean')
         return headless;
@@ -37,7 +38,7 @@ function resolveHeadless(headless) {
  * 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;
+    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, api, commands, screenshotFailures, isolate, } = opts;
     if (!name.trim())
         throw new TypeError('browser project name must not be empty');
     if (instances.length === 0) {
@@ -70,6 +71,19 @@ export function defineBrowserTestConfig(opts = {}) {
     if (setupFiles) {
         test.setupFiles = [...setupFiles];
     }
+    if (api) {
+        if (vitestMajor() >= 5)
+            test.api = { ...api };
+        // Vitest 4's browser server reads its own `api`; Vitest 5's types no longer carry it.
+        else
+            test.browser.api = { ...api };
+    }
+    if (commands)
+        test.browser = { ...test.browser, commands: { ...commands } };
+    if (screenshotFailures !== undefined)
+        test.browser = { ...test.browser, screenshotFailures };
+    if (isolate !== undefined)
+        test.isolate = isolate;
     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

package/dist/esm/vitest-major.js

@@ -0,0 +1,13 @@
+import { version } from 'vitest/node';
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+export function vitestMajor() {
+    const major = Number.parseInt(version, 10);
+    if (!Number.isFinite(major))
+        throw new Error(`unrecognised Vitest version: ${version}`);
+    return major;
+}

package/dist/types/browser-config.d.cts

@@ -1,5 +1,5 @@
 import { type PlaywrightProviderOptions } from '@vitest/browser-playwright';
-import type { TestUserConfig } from 'vitest/node';
+import type { BrowserConfigOptions, TestUserConfig } from 'vitest/node';
 import { type ChromiumGpuMode } from './chromium-launch.js';
 /**
  * A single browser instance entry, as accepted by Vitest Browser Mode's
@@ -64,6 +64,25 @@ export interface BrowserTestConfigOptions {
      * verified your suite tolerates concurrent browser contexts.
      */
     fileParallelism?: boolean;
+    /**
+     * The browser server's address, such as the port a CI slot or a local
+     * port allocator assigned (`{ port, strictPort: true }`). Placed where the
+     * installed Vitest reads it: the top-level `api` on Vitest 5, `browser.api`
+     * on Vitest 4. Omitted, Vitest's default port is used.
+     */
+    api?: BrowserApiConfig;
+    /** Custom browser commands (`browser.commands`), e.g. a pointer drawn along a path. */
+    commands?: NonNullable<BrowserConfigOptions['commands']>;
+    /** `browser.screenshotFailures`. Omitted, Vitest's default applies. */
+    screenshotFailures?: boolean;
+    /** The top-level `isolate` (Vitest 5 retired `browser.isolate` for it). Omitted, Vitest's default applies. */
+    isolate?: boolean;
+}
+/** The browser server's address options: the subset Vitest 4's `browser.api` and Vitest 5's `api` share. */
+export interface BrowserApiConfig {
+    port?: number;
+    strictPort?: boolean;
+    host?: string;
 }
 /**
  * Builds a `test` fragment for a Vitest Browser Mode project, wired for

package/dist/types/browser-config.d.ts

@@ -1,5 +1,5 @@
 import { type PlaywrightProviderOptions } from '@vitest/browser-playwright';
-import type { TestUserConfig } from 'vitest/node';
+import type { BrowserConfigOptions, TestUserConfig } from 'vitest/node';
 import { type ChromiumGpuMode } from './chromium-launch.js';
 /**
  * A single browser instance entry, as accepted by Vitest Browser Mode's
@@ -64,6 +64,25 @@ export interface BrowserTestConfigOptions {
      * verified your suite tolerates concurrent browser contexts.
      */
     fileParallelism?: boolean;
+    /**
+     * The browser server's address, such as the port a CI slot or a local
+     * port allocator assigned (`{ port, strictPort: true }`). Placed where the
+     * installed Vitest reads it: the top-level `api` on Vitest 5, `browser.api`
+     * on Vitest 4. Omitted, Vitest's default port is used.
+     */
+    api?: BrowserApiConfig;
+    /** Custom browser commands (`browser.commands`), e.g. a pointer drawn along a path. */
+    commands?: NonNullable<BrowserConfigOptions['commands']>;
+    /** `browser.screenshotFailures`. Omitted, Vitest's default applies. */
+    screenshotFailures?: boolean;
+    /** The top-level `isolate` (Vitest 5 retired `browser.isolate` for it). Omitted, Vitest's default applies. */
+    isolate?: boolean;
+}
+/** The browser server's address options: the subset Vitest 4's `browser.api` and Vitest 5's `api` share. */
+export interface BrowserApiConfig {
+    port?: number;
+    strictPort?: boolean;
+    host?: string;
 }
 /**
  * Builds a `test` fragment for a Vitest Browser Mode project, wired for

package/dist/types/vitest-major.d.cts

@@ -0,0 +1,7 @@
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+export declare function vitestMajor(): number;

package/dist/types/vitest-major.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+export declare function vitestMajor(): number;

package/docs/guides/vitest.md

@@ -39,3 +39,18 @@ discover on its own) that must also be merged into your top-level
 `vite.config.ts`'s `optimizeDeps.include` — read them off the returned
 fragment's `__optimizeDepsInclude` field, since Vitest's `test` block has no
 `optimizeDeps` field of its own.
+
+A game whose suite needs more of Vitest's browser options passes them through
+rather than spreading over the fragment:
+
+- `api` is the browser server's address, such as the port a CI slot or a
+  local port allocator assigned, with `strictPort: true` so a taken port
+  fails rather than drifting. It is placed where the installed Vitest reads
+  it: the top-level `api` on Vitest 5 (which ignores `browser.api`),
+  `browser.api` on Vitest 4.
+- `commands` registers custom browser commands (`browser.commands`), such as
+  a pointer drawn along a path that `userEvent` cannot draw.
+- `screenshotFailures` sets `browser.screenshotFailures`.
+- `isolate` sets the top-level `isolate`, which replaced `browser.isolate`.
+
+Each is left to Vitest's default when it is not given.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-harness",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Release-grade browser QA primitives for TypeScript games: silent Playwright/Vitest sessions, deterministic screenshots, runtime proof, and Lighthouse gates.",
   "type": "module",
   "license": "MIT",