game-harness 1.1.2 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes are recorded here. Releases follow
 [Semantic Versioning](https://semver.org/) and are generated from Conventional
 Commits by release-please.
 
+## [1.3.0](https://github.com/jbcom/game-harness/compare/game-harness-v1.2.0...game-harness-v1.3.0) (2026-10-10)
+
+
+### Features
+
+* **chromium:** add the macos-hardware-metal gpu mode ([008f277](https://github.com/jbcom/game-harness/commit/008f2770886e73a2d323b65bb3f6373ea21be426))
+
+## [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/README.md

@@ -180,6 +180,11 @@ make WebGL start. The default `auto` profile lets Chromium select the native
 renderer (including Metal on macOS). `software` is an explicit SwiftShader
 fallback. `linux-hardware-vulkan` applies the reviewed Mesa/ANGLE flags and
 `EGL_PLATFORM=surfaceless` for a runner that exposes `/dev/dri/renderD128`.
+`macos-hardware-metal` asks ANGLE for its Metal backend (`--use-angle=metal
+--ignore-gpu-blocklist`); it is the profile for an Apple Silicon Mac with no
+window session, where `headless: true` still reaches the real GPU (no display
+server or Xvfb is involved), so a render host does not fall back to
+SwiftShader.
 
 Vitest's interactive UI is disabled by default even though the Chromium window
 remains visible. This gives Playwright a fixed viewport and a deterministic
@@ -252,11 +257,12 @@ const browser = await chromium.launch({ args, env, headless: false });
 `createChromiumLaunchProfile()` is the peer-free primitive behind both
 `definePlaywrightConfig()` and `defineBrowserTestConfig()` — use it directly
 when driving Chromium yourself (a custom launch script, `production-runtime`'s
-own internals, or a non-Playwright automation layer). It resolves one of three
+own internals, or a non-Playwright automation layer). It resolves one of four
 renderer policies (`auto` leaves selection to Chromium; `software` opts into
 SwiftShader explicitly; `linux-hardware-vulkan` applies the reviewed
 Mesa/ANGLE flags plus `EGL_PLATFORM=surfaceless` for a runner exposing
-`/dev/dri/renderD128`) and always de-duplicates and appends `--mute-audio`
+`/dev/dri/renderD128`; `macos-hardware-metal` asks ANGLE for its Metal backend
+with `--use-angle=metal --ignore-gpu-blocklist`) and always de-duplicates and appends `--mute-audio`
 last, so a caller-supplied arg list can never accidentally drop the silence
 guard. Every profile also carries `CHROMIUM_ANTI_THROTTLING_ARGS`
 (`--disable-background-timer-throttling`, `--disable-renderer-backgrounding`,

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/chromium-launch.js

@@ -11,6 +11,7 @@ const GPU_ARGS = {
         '--use-angle=vulkan',
         '--ignore-gpu-blocklist',
     ],
+    'macos-hardware-metal': ['--use-angle=metal', '--ignore-gpu-blocklist'],
 };
 /**
  * Keeps timers and rendering on schedule in pages Chromium considers

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/chromium-launch.js

@@ -7,6 +7,7 @@ const GPU_ARGS = {
         '--use-angle=vulkan',
         '--ignore-gpu-blocklist',
     ],
+    'macos-hardware-metal': ['--use-angle=metal', '--ignore-gpu-blocklist'],
 };
 /**
  * Keeps timers and rendering on schedule in pages Chromium considers

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/chromium-launch.d.cts

@@ -1,12 +1,16 @@
 /** Browser renderer policy for agent-controlled Chromium sessions. */
-export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan';
+export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan' | 'macos-hardware-metal';
 export type ChromiumEnvironment = Record<string, string | undefined>;
 export interface ChromiumLaunchProfileOptions {
     /**
-     * `auto` leaves renderer selection to Chromium (Metal on macOS, the native
-     * desktop stack elsewhere). `software` opts into SwiftShader explicitly.
+     * `auto` leaves renderer selection to Chromium (Metal on macOS in a headed
+     * window, the native desktop stack elsewhere). `software` opts into
+     * SwiftShader explicitly.
      * `linux-hardware-vulkan` is a proven Mesa/ANGLE profile for a
      * Linux runner with `/dev/dri/renderD128` passed through.
+     * `macos-hardware-metal` asks ANGLE for its Metal backend, which gives a
+     * headless Chromium on an Apple Silicon Mac (no window session needed) the
+     * real GPU instead of SwiftShader.
      */
     gpuMode?: ChromiumGpuMode;
     /** Additional Chromium arguments, de-duplicated ahead of `--mute-audio`. */

package/dist/types/chromium-launch.d.ts

@@ -1,12 +1,16 @@
 /** Browser renderer policy for agent-controlled Chromium sessions. */
-export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan';
+export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan' | 'macos-hardware-metal';
 export type ChromiumEnvironment = Record<string, string | undefined>;
 export interface ChromiumLaunchProfileOptions {
     /**
-     * `auto` leaves renderer selection to Chromium (Metal on macOS, the native
-     * desktop stack elsewhere). `software` opts into SwiftShader explicitly.
+     * `auto` leaves renderer selection to Chromium (Metal on macOS in a headed
+     * window, the native desktop stack elsewhere). `software` opts into
+     * SwiftShader explicitly.
      * `linux-hardware-vulkan` is a proven Mesa/ANGLE profile for a
      * Linux runner with `/dev/dri/renderD128` passed through.
+     * `macos-hardware-metal` asks ANGLE for its Metal backend, which gives a
+     * headless Chromium on an Apple Silicon Mac (no window session needed) the
+     * real GPU instead of SwiftShader.
      */
     gpuMode?: ChromiumGpuMode;
     /** Additional Chromium arguments, de-duplicated ahead of `--mute-audio`. */

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/chromium-and-silent-qa.md

@@ -17,10 +17,13 @@ const browser = await chromium.launch({ args, env, headless: false });
 `definePlaywrightConfig()` and `defineBrowserTestConfig()` — use it directly
 when driving Chromium yourself (a custom launch script, `production-runtime`'s
 own internals, or a non-Playwright automation layer). It resolves one of
-three renderer policies (`auto` leaves selection to Chromium; `software`
+four renderer policies (`auto` leaves selection to Chromium; `software`
 opts into SwiftShader explicitly; `linux-hardware-vulkan` applies the
 reviewed Mesa/ANGLE flags plus `EGL_PLATFORM=surfaceless` for a runner
-exposing `/dev/dri/renderD128`) and always de-duplicates and appends
+exposing `/dev/dri/renderD128`; `macos-hardware-metal` asks ANGLE for its
+Metal backend with `--use-angle=metal --ignore-gpu-blocklist`, which a
+headless Chromium on an Apple Silicon Mac with no window session honours by
+using the real GPU) and always de-duplicates and appends
 `--mute-audio` last, so a caller-supplied arg list can never accidentally
 drop the silence guard.
 

package/docs/guides/playwright.md

@@ -43,7 +43,11 @@ to make WebGL start. The default `auto` profile lets Chromium select the
 native renderer (including Metal on macOS). `software` is an explicit
 SwiftShader fallback. `linux-hardware-vulkan` applies the reviewed
 Mesa/ANGLE flags and `EGL_PLATFORM=surfaceless` for a runner that exposes
-`/dev/dri/renderD128`.
+`/dev/dri/renderD128`. `macos-hardware-metal` asks ANGLE for its Metal backend
+(`--use-angle=metal --ignore-gpu-blocklist`); it is the profile for an Apple
+Silicon Mac with no window session, where `headless: true` still reaches the
+real GPU (no display server or Xvfb is involved), so a render host does not
+fall back to SwiftShader.
 
 A Gitea runner job using the hardware profile must install
 `mesa-vulkan-drivers` and `xvfb`, require the render device with

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.3.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",