Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(sdk-tests): an unavailable engine build fails, instead of skipping

esengine16b2816c3fc6
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index d9467feeb..ce2bb3e58 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -149,12 +149,15 @@ jobs:
# Every static gate, from the one list in tools/gates.mjs. CI and the
# pre-push hook used to enumerate their own — seventeen gates ran only on a
# machine with the hook installed, and five only here.
- - name: Static gates
+ # This job is the FAST feedback and deliberately does not wait for
+ # Emscripten, so it cannot cover the engine boundary. It says so: without the
+ # declaration the SDK suite now refuses to run rather than reporting 300
+ # unreachable tests as skipped. `test-engine` covers them where the wasm is.
+ - name: Static gates (incl. the SDK, editor, plugin and compiler suites)
+ env:
+ SDK_TEST_MODE: no-wasm
run: node tools/run-gates.mjs --scope ci
- - name: Run SDK tests
- run: pnpm --filter ./sdk exec vitest run
-
# The Android packaging tests check what we write against implementations that
# are not ours. androguard decodes the binary manifest; bundletool is the App
# Bundle format's own authority, and the runner has the JVM it needs — the
diff --git a/sdk/tests/dragonbones-controller.integration.test.ts b/sdk/tests/dragonbones-controller.integration.test.ts
index e37805a77..0838196dc 100644
--- a/sdk/tests/dragonbones-controller.integration.test.ts
+++ b/sdk/tests/dragonbones-controller.integration.test.ts
@@ -8,7 +8,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { DragonBonesModuleController } from '../src/dragonbones/DragonBonesController';
import { wrapDragonBonesModule, type DragonBonesWasmModule } from '../src/dragonbones/DragonBonesModuleLoader';
@@ -17,7 +17,7 @@ const DB_WASM = resolve(WASM_DIR, 'dragonbones.wasm');
const ASSET_DIR = resolve(__dirname, 'assets/dragonbones');
const SKE = resolve(ASSET_DIR, 'DragonBoy_ske.json');
const TEX = resolve(ASSET_DIR, 'DragonBoy_tex.json');
-const HAS_ASSETS = existsSync(DB_WASM) && existsSync(SKE);
+const HAS_ASSETS = hasSideModule('dragonbones') && existsSync(SKE);
describe.skipIf(!HAS_ASSETS)('DragonBonesModuleController', () => {
let controller: DragonBonesModuleController;
diff --git a/sdk/tests/dragonbones-load.integration.test.ts b/sdk/tests/dragonbones-load.integration.test.ts
index 4cb296ae8..87b78e140 100644
--- a/sdk/tests/dragonbones-load.integration.test.ts
+++ b/sdk/tests/dragonbones-load.integration.test.ts
@@ -9,14 +9,14 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
const DB_JS = resolve(WASM_DIR, 'dragonbones.js');
const DB_WASM = resolve(WASM_DIR, 'dragonbones.wasm');
const ASSET_DIR = resolve(__dirname, 'assets/dragonbones');
const SKE = resolve(ASSET_DIR, 'DragonBoy_ske.json');
const TEX = resolve(ASSET_DIR, 'DragonBoy_tex.json');
-const HAS_ASSETS = existsSync(DB_WASM) && existsSync(SKE);
+const HAS_ASSETS = hasSideModule('dragonbones') && existsSync(SKE);
interface DbModule {
ccall(name: string, ret: string | null, sig: string[], args: unknown[]): never;
diff --git a/sdk/tests/dragonbones-manager.integration.test.ts b/sdk/tests/dragonbones-manager.integration.test.ts
index 51720552f..6a8ef41ed 100644
--- a/sdk/tests/dragonbones-manager.integration.test.ts
+++ b/sdk/tests/dragonbones-manager.integration.test.ts
@@ -9,7 +9,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { DragonBonesManager } from '../src/dragonbones/DragonBonesManager';
import { DragonBonesModuleController } from '../src/dragonbones/DragonBonesController';
import { wrapDragonBonesModule, type DragonBonesWasmModule } from '../src/dragonbones/DragonBonesModuleLoader';
@@ -20,7 +20,7 @@ const DB_WASM = resolve(WASM_DIR, 'dragonbones.wasm');
const ASSET_DIR = resolve(__dirname, 'assets/dragonbones');
const SKE = resolve(ASSET_DIR, 'DragonBoy_ske.json');
const TEX = resolve(ASSET_DIR, 'DragonBoy_tex.json');
-const HAS_ASSETS = existsSync(DB_WASM) && existsSync(SKE);
+const HAS_ASSETS = hasSideModule('dragonbones') && existsSync(SKE);
const e = (n: number): Entity => n as unknown as Entity;
diff --git a/sdk/tests/globalSetup.ts b/sdk/tests/globalSetup.ts
new file mode 100644
index 000000000..acb08e69a
--- /dev/null
+++ b/sdk/tests/globalSetup.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file globalSetup.ts — the engine build has to be REACHABLE before a run
+ * claims to have covered the boundary.
+ *
+ * @details A `skip` says "this test does not apply to how you are configured".
+ * It was also saying "I could not get at the thing this test needs",
+ * and those read the same in a summary: an invocation whose working
+ * directory put the build outside vite's reach reported 5110 passed and
+ * 309 skipped, no failures, while 43 suites had not run at all.
+ *
+ * So the environment is proved ONCE, here, by doing exactly what the
+ * suites do — importing the engine's glue — and a run that cannot is
+ * stopped before it can report a partial pass as a clean one. A run
+ * that genuinely has no engine build says so with SDK_TEST_MODE, and
+ * then a skip means what it should.
+ */
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { WASM_DIR, WASM_FILE, SIDE_MODULES, NO_WASM_MODE } from './helpers/loadWasm';
+
+/** The package this suite belongs to — where it has to be run from. */
+const SDK_ROOT = resolve(__dirname, '..');
+
+/** The command that is known to place the build within reach. */
+const CANONICAL = 'pnpm --filter ./sdk test (or: cd sdk && npx vitest run)';
+
+export default async function setup(): Promise<void> {
+ if (NO_WASM_MODE) {
+ console.warn(
+ '\n[sdk-tests] SDK_TEST_MODE=no-wasm — the engine boundary suites will NOT run.\n'
+ + ' This run does not cover the C++/TS boundary, the side modules, '
+ + 'or anything that poses a skeleton.\n',
+ );
+ return;
+ }
+
+ if (!existsSync(WASM_FILE)) {
+ throw new Error(
+ `no engine build at ${WASM_FILE}.\n`
+ + ' The boundary suites need it, and skipping them would report a partial run '
+ + 'as a clean one.\n'
+ + ' Build it (`node build-tools/cli.js build -t web`), or declare the gap with '
+ + 'SDK_TEST_MODE=no-wasm.',
+ );
+ }
+
+ // Existence is not REACH: vite derives its allowed roots from the working
+ // directory, not from `--root`. Checked rather than probed — an import from
+ // here takes a different loader than the test files do.
+ if (resolve(process.cwd()) !== resolve(SDK_ROOT)) {
+ throw new Error(
+ `the SDK suite must run with ${SDK_ROOT} as the working directory.\n`
+ + ` It is ${process.cwd()}, and from there the engine build at ${WASM_DIR}\n`
+ + ' is outside what this run may load — the boundary suites would not collect,\n'
+ + ' and vitest would report their tests as SKIPPED rather than as unavailable.\n'
+ + ` Run the SDK suite as: ${CANONICAL}`,
+ );
+ }
+
+ const missing = SIDE_MODULES.filter((name) => !existsSync(resolve(WASM_DIR, `${name}.wasm`)));
+ if (missing.length === 0) return;
+ // Said out loud rather than failed: a partial build is a normal thing to be
+ // iterating on. Silence is what it may not be.
+ const message = `\n[sdk-tests] ${missing.length} side module(s) not built: ${missing.join(', ')}\n`
+ + ' Their suites will not run. Build with `node build-tools/cli.js build -t all`.\n';
+ if (process.env.ESTELLA_REQUIRE_WASM) {
+ throw new Error(`${message} ESTELLA_REQUIRE_WASM is set — this job is meant to cover them.`);
+ }
+ console.warn(message);
+}
diff --git a/sdk/tests/helpers/loadWasm.ts b/sdk/tests/helpers/loadWasm.ts
index d4562df20..ba9b6a096 100644
--- a/sdk/tests/helpers/loadWasm.ts
+++ b/sdk/tests/helpers/loadWasm.ts
@@ -38,20 +38,26 @@ export const WASM_DIR = resolveWasmDir();
/** Absolute path to the built esengine.wasm binary. */
export const WASM_FILE = resolve(WASM_DIR, 'esengine.wasm');
-/** True when a built WASM SDK is available to run boundary integration tests. */
-export const HAS_WASM = existsSync(WASM_FILE);
+/**
+ * The side modules the SDK's suites load, beside the engine itself. Declared so
+ * one place can say what a run will and will not cover.
+ */
+export const SIDE_MODULES = [
+ 'physics', 'physics3d', 'dragonbones', 'basis', 'videodec',
+ 'spine21', 'spine38', 'spine41', 'spine42', 'spine43',
+] as const;
-// A skip is the right answer on a machine that has not built the engine, and the
-// WRONG one in CI: a job meant to cover these tests would report success having
-// run none of them, which is how 25 files stayed green-by-absence while the code
-// under them changed. The job that provides the wasm sets ESTELLA_REQUIRE_WASM,
-// and here that turns a silent skip into a loud failure.
-if (!HAS_WASM && process.env.ESTELLA_REQUIRE_WASM) {
- throw new Error(
- `ESTELLA_REQUIRE_WASM is set but no engine build was found at ${WASM_FILE}. ` +
- 'The wasm artifact did not reach this job — these tests would have been skipped.',
- );
-}
+/**
+ * Whether this run DECLARED that it has no engine build — the only reason a
+ * boundary suite may skip.
+ *
+ * Inferred from the filesystem, "missing" and "unreachable" both came out as
+ * `skipped`, which reads as "not applicable" rather than "unavailable".
+ */
+export const NO_WASM_MODE = process.env.SDK_TEST_MODE === 'no-wasm';
+
+/** True unless this run declared it has no engine build. */
+export const HAS_WASM = !NO_WASM_MODE;
let cachedModule: ESEngineModule | null = null;
@@ -79,6 +85,7 @@ export async function loadSideModule<T>(name: string): Promise<T> {
return await factory({ wasmBinary }) as T;
}
-/** Whether a side module was built alongside the engine. */
+/** Whether a side module was built alongside the engine. False for every module
+ * in a declared no-wasm run, so one flag turns the whole corpus off. */
export const hasSideModule = (name: string): boolean =>
- existsSync(resolve(WASM_DIR, `${name}.wasm`));
+ !NO_WASM_MODE && existsSync(resolve(WASM_DIR, `${name}.wasm`));
diff --git a/sdk/tests/spine-abi-cost.test.ts b/sdk/tests/spine-abi-cost.test.ts
index 2db306b12..722a2b934 100644
--- a/sdk/tests/spine-abi-cost.test.ts
+++ b/sdk/tests/spine-abi-cost.test.ts
@@ -20,7 +20,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import type { SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineRuntime } from '../src/spine/SpineRuntime';
import type { SpineAssetValue, SpineEraBinding } from '../src/spine/prepareSpine';
@@ -31,7 +31,7 @@ const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine/spineboy-38');
const SKEL = resolve(FIXTURES, 'spineboy-pro.skel');
const ATLAS = resolve(FIXTURES, 'spineboy.atlas');
-const HAS_ASSETS = existsSync(SPINE38_WASM) && existsSync(SKEL) && existsSync(ATLAS);
+const HAS_ASSETS = hasSideModule('spine38') && existsSync(SKEL) && existsSync(ATLAS);
/** Every export call, by name — the module's own `cwrap` is the one door. */
interface Crossings {
diff --git a/sdk/tests/spine-batch-storage.test.ts b/sdk/tests/spine-batch-storage.test.ts
index 3b9de5bf4..4007b6f69 100644
--- a/sdk/tests/spine-batch-storage.test.ts
+++ b/sdk/tests/spine-batch-storage.test.ts
@@ -21,7 +21,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { withScratch } from '../src/wasm/wasmScratch';
@@ -53,7 +53,7 @@ const ASSETS = [
},
] as const;
-const HAS_ASSETS = existsSync(SPINE38_WASM)
+const HAS_ASSETS = hasSideModule('spine38')
&& ASSETS.every((a) => existsSync(resolve(FIXTURES, a.skel)));
/** The four u32 counters `spine_probe_storage` writes, in order. */
diff --git a/sdk/tests/spine-bounds-certification.test.ts b/sdk/tests/spine-bounds-certification.test.ts
index 3237c1360..46973ac34 100644
--- a/sdk/tests/spine-bounds-certification.test.ts
+++ b/sdk/tests/spine-bounds-certification.test.ts
@@ -17,7 +17,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import { SpineModuleController } from '../src/spine/SpineController';
import type { SpineWasmModule } from '../src/spine/SpineModuleLoader';
@@ -32,7 +32,7 @@ import type { SyntheticOptions } from './helpers/syntheticSpine';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM)
+const HAS_WASM = hasSideModule('spine38')
&& existsSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel'));
let raw: SpineWasmModule;
diff --git a/sdk/tests/spine-clip-budget.test.ts b/sdk/tests/spine-clip-budget.test.ts
index 03f10b64b..3d559ce35 100644
--- a/sdk/tests/spine-clip-budget.test.ts
+++ b/sdk/tests/spine-clip-budget.test.ts
@@ -18,7 +18,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import { SpineModuleController } from '../src/spine/SpineController';
import type { SpineWasmModule } from '../src/spine/SpineModuleLoader';
@@ -29,7 +29,7 @@ import type { SyntheticOptions } from './helpers/syntheticSpine';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM);
+const HAS_WASM = hasSideModule('spine38');
const QUADS = 16;
let raw: SpineWasmModule;
diff --git a/sdk/tests/spine-clip-convex-bypass.test.ts b/sdk/tests/spine-clip-convex-bypass.test.ts
index bb79ebf3e..3feca0614 100644
--- a/sdk/tests/spine-clip-convex-bypass.test.ts
+++ b/sdk/tests/spine-clip-convex-bypass.test.ts
@@ -20,7 +20,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { withScratch } from '../src/wasm/wasmScratch';
@@ -30,7 +30,7 @@ import type { SyntheticOptions } from './helpers/syntheticSpine';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM);
+const HAS_WASM = hasSideModule('spine38');
const STAGE_EMIT = 5;
const QUADS = 8;
diff --git a/sdk/tests/spine-clip-parity.test.ts b/sdk/tests/spine-clip-parity.test.ts
index 83a1a56af..1bbaf354c 100644
--- a/sdk/tests/spine-clip-parity.test.ts
+++ b/sdk/tests/spine-clip-parity.test.ts
@@ -18,7 +18,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { withScratch } from '../src/wasm/wasmScratch';
@@ -31,7 +31,7 @@ const OVERRIDE = process.env.SPINE_WASM_OVERRIDE;
const SPINE38_JS = OVERRIDE ? `${OVERRIDE}.js` : resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = OVERRIDE ? `${OVERRIDE}.wasm` : resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM);
+const HAS_WASM = hasSideModule('spine38');
const QUADS = 16;
/** FNV-1a over every triangle's three vertices, in draw order. */
diff --git a/sdk/tests/spine-clip-stages.test.ts b/sdk/tests/spine-clip-stages.test.ts
index 6e1f56959..256ce99f2 100644
--- a/sdk/tests/spine-clip-stages.test.ts
+++ b/sdk/tests/spine-clip-stages.test.ts
@@ -13,7 +13,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { withScratch } from '../src/wasm/wasmScratch';
@@ -23,7 +23,7 @@ import type { SyntheticOptions } from './helpers/syntheticSpine';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM);
+const HAS_WASM = hasSideModule('spine38');
/** The thirteen counters `spine_probe_counts` writes, in order. */
const COUNTERS = [
diff --git a/sdk/tests/spine-clip-start.test.ts b/sdk/tests/spine-clip-start.test.ts
index 88757d852..0e20357fc 100644
--- a/sdk/tests/spine-clip-start.test.ts
+++ b/sdk/tests/spine-clip-start.test.ts
@@ -17,7 +17,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { SpineRuntime } from '../src/spine/SpineRuntime';
@@ -30,7 +30,7 @@ import type { SyntheticOptions } from './helpers/syntheticSpine';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM);
+const HAS_WASM = hasSideModule('spine38');
const CLIP_START_FULL = 6;
const STAGE_EMIT = 5;
diff --git a/sdk/tests/spine-clip.integration.test.ts b/sdk/tests/spine-clip.integration.test.ts
index bacf51dbb..e6486e0b2 100644
--- a/sdk/tests/spine-clip.integration.test.ts
+++ b/sdk/tests/spine-clip.integration.test.ts
@@ -22,7 +22,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule, type SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineModuleController } from '../src/spine/SpineController';
@@ -31,7 +31,7 @@ const SPINE42_WASM = resolve(WASM_DIR, 'spine42.wasm');
const ASSET_DIR = resolve(__dirname, '../../third_party/spine-runtimes-4.2/examples/tank/export');
const SKEL = resolve(ASSET_DIR, 'tank-pro.skel');
const ATLAS = resolve(ASSET_DIR, 'tank.atlas');
-const HAS_ASSETS = existsSync(SPINE42_WASM) && existsSync(SKEL) && existsSync(ATLAS);
+const HAS_ASSETS = hasSideModule('spine42') && existsSync(SKEL) && existsSync(ATLAS);
interface Mesh { verts: number[]; tris: number; batches: number; }
diff --git a/sdk/tests/spine-demand-driven-pose.test.ts b/sdk/tests/spine-demand-driven-pose.test.ts
index 2ac3f2bb6..70bca61d0 100644
--- a/sdk/tests/spine-demand-driven-pose.test.ts
+++ b/sdk/tests/spine-demand-driven-pose.test.ts
@@ -19,7 +19,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import type { SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineRuntime } from '../src/spine/SpineRuntime';
import { certifyBounds } from '../src/spine/spineBounds';
@@ -32,7 +32,7 @@ import { fakeSpineModule, fakeSpineEra } from './helpers/fakeSpineModule';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM)
+const HAS_WASM = hasSideModule('spine38')
&& existsSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel'));
const DT = 1 / 60;
const CERTIFIED = certifyBounds({ minX: -300, minY: -20, maxX: 300, maxY: 800 });
diff --git a/sdk/tests/spine-extract-stages.test.ts b/sdk/tests/spine-extract-stages.test.ts
index 316abcef6..b7224604c 100644
--- a/sdk/tests/spine-extract-stages.test.ts
+++ b/sdk/tests/spine-extract-stages.test.ts
@@ -18,7 +18,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { SpineRuntime } from '../src/spine/SpineRuntime';
@@ -34,7 +34,7 @@ const ASSETS = [
{ name: 'raptor', skel: 'raptor-38/raptor-pro.skel', atlas: 'raptor-38/raptor.atlas' },
{ name: 'coin', skel: 'coin-38/coin-pro.skel', atlas: 'coin-38/coin.atlas' },
];
-const HAS_ASSETS = existsSync(SPINE38_WASM)
+const HAS_ASSETS = hasSideModule('spine38')
&& ASSETS.every((a) => existsSync(resolve(FIXTURES, a.skel)));
/** The nine counters `spine_probe_counts` writes, in order. */
diff --git a/sdk/tests/spine-observability.test.ts b/sdk/tests/spine-observability.test.ts
index 8dfe0f35b..3afcc2349 100644
--- a/sdk/tests/spine-observability.test.ts
+++ b/sdk/tests/spine-observability.test.ts
@@ -15,7 +15,7 @@
import { describe, it, expect, beforeAll, vi, afterEach } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import type { SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineRuntime } from '../src/spine/SpineRuntime';
import { SpineTimeWindow } from '../src/spine/spineMetrics';
@@ -27,7 +27,7 @@ const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine/spineboy-38');
const SKEL = resolve(FIXTURES, 'spineboy-pro.skel');
const ATLAS = resolve(FIXTURES, 'spineboy.atlas');
-const HAS_ASSETS = existsSync(SPINE38_WASM) && existsSync(SKEL) && existsSync(ATLAS);
+const HAS_ASSETS = hasSideModule('spine38') && existsSync(SKEL) && existsSync(ATLAS);
let module38: SpineWasmModule;
let skelData: Uint8Array;
diff --git a/sdk/tests/spine-phase-split.test.ts b/sdk/tests/spine-phase-split.test.ts
index a3bd25bbc..3c2099308 100644
--- a/sdk/tests/spine-phase-split.test.ts
+++ b/sdk/tests/spine-phase-split.test.ts
@@ -19,7 +19,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { withScratch } from '../src/wasm/wasmScratch';
@@ -37,7 +37,7 @@ const ASSETS = [
{ name: 'coin (clipped)', skel: 'coin-38/coin-pro.skel', atlas: 'coin-38/coin.atlas', animation: 'animation' },
{ name: 'tank (concave clip)', skel: 'tank-38/tank-pro.skel', atlas: 'tank-38/tank.atlas', animation: 'shoot' },
];
-const HAS_WASM = existsSync(SPINE38_WASM)
+const HAS_WASM = hasSideModule('spine38')
&& ASSETS.every((a) => existsSync(resolve(FIXTURES, a.skel)));
const DT = 1 / 60;
diff --git a/sdk/tests/spine-pose-demand.test.ts b/sdk/tests/spine-pose-demand.test.ts
index 83e3e9c29..a0f272703 100644
--- a/sdk/tests/spine-pose-demand.test.ts
+++ b/sdk/tests/spine-pose-demand.test.ts
@@ -19,7 +19,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { SpineRuntime } from '../src/spine/SpineRuntime';
@@ -30,7 +30,7 @@ import { withScratch } from '../src/wasm/wasmScratch';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM)
+const HAS_WASM = hasSideModule('spine38')
&& existsSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel'));
let raw: SpineWasmModule;
diff --git a/sdk/tests/spine-pose-materialization.test.ts b/sdk/tests/spine-pose-materialization.test.ts
index 1385137cd..c5f7b5144 100644
--- a/sdk/tests/spine-pose-materialization.test.ts
+++ b/sdk/tests/spine-pose-materialization.test.ts
@@ -17,7 +17,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import type { SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineRuntime } from '../src/spine/SpineRuntime';
import type { SpineEraBinding } from '../src/spine/prepareSpine';
@@ -26,7 +26,7 @@ import type { Entity } from '../src/types';
const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
-const HAS_WASM = existsSync(SPINE38_WASM)
+const HAS_WASM = hasSideModule('spine38')
&& existsSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel'));
let raw: SpineWasmModule;
diff --git a/sdk/tests/spine-pose-stages.test.ts b/sdk/tests/spine-pose-stages.test.ts
index c1c487829..d13bde704 100644
--- a/sdk/tests/spine-pose-stages.test.ts
+++ b/sdk/tests/spine-pose-stages.test.ts
@@ -17,7 +17,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { withScratch } from '../src/wasm/wasmScratch';
@@ -27,7 +27,7 @@ const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');
const SKEL = 'spineboy-38/spineboy-pro.skel';
const ATLAS = 'spineboy-38/spineboy.atlas';
-const HAS_ASSETS = existsSync(SPINE38_WASM) && existsSync(resolve(FIXTURES, SKEL));
+const HAS_ASSETS = hasSideModule('spine38') && existsSync(resolve(FIXTURES, SKEL));
/** The nine counters `spine_probe_pose_counts` writes, in order. */
const COUNTERS = [
diff --git a/sdk/tests/spine21-load.integration.test.ts b/sdk/tests/spine21-load.integration.test.ts
index 7bb38103a..036c5ef81 100644
--- a/sdk/tests/spine21-load.integration.test.ts
+++ b/sdk/tests/spine21-load.integration.test.ts
@@ -17,7 +17,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule, type SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineModuleController } from '../src/spine/SpineController';
@@ -28,7 +28,7 @@ const BOY_JSON = resolve(ROOT, 'spine-c/data/spineboy.json');
const BOY_ATLAS = resolve(ROOT, 'spine-c/data/spineboy.atlas');
const GOBLINS_JSON = resolve(ROOT, 'spine-as3/spine-as3-example/src/goblins-mesh.json');
const GOBLINS_ATLAS = resolve(ROOT, 'spine-as3/spine-as3-example/src/goblins-mesh.atlas');
-const HAS_ASSETS = existsSync(SPINE21_WASM) && existsSync(BOY_JSON);
+const HAS_ASSETS = hasSideModule('spine21') && existsSync(BOY_JSON);
interface Batch {
vertexCount: number;
diff --git a/sdk/tests/spine38-load.integration.test.ts b/sdk/tests/spine38-load.integration.test.ts
index e792e5b67..cf7dd85ee 100644
--- a/sdk/tests/spine38-load.integration.test.ts
+++ b/sdk/tests/spine38-load.integration.test.ts
@@ -14,7 +14,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule, type SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineModuleController } from '../src/spine/SpineController';
@@ -23,7 +23,7 @@ const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const ASSET_DIR = resolve(__dirname, '../../third_party/spine-runtimes-3.8/examples/spineboy/export');
const SKEL = resolve(ASSET_DIR, 'spineboy-pro.skel');
const ATLAS = resolve(ASSET_DIR, 'spineboy.atlas');
-const HAS_SPINE38 = existsSync(SPINE38_WASM) && existsSync(SKEL);
+const HAS_SPINE38 = hasSideModule('spine38') && existsSync(SKEL);
describe.skipIf(!HAS_SPINE38)('Spine 3.8 side module loads + animates a real 3.8 asset', () => {
let controller: SpineModuleController;
diff --git a/sdk/tests/spine43-load.integration.test.ts b/sdk/tests/spine43-load.integration.test.ts
index f39a77e17..825e051e9 100644
--- a/sdk/tests/spine43-load.integration.test.ts
+++ b/sdk/tests/spine43-load.integration.test.ts
@@ -16,7 +16,7 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule, type SpineWasmModule } from '../src/spine/SpineModuleLoader';
import { SpineModuleController } from '../src/spine/SpineController';
@@ -27,7 +27,7 @@ const SKEL = resolve(ASSET_DIR, 'spineboy-pro.skel');
const JSON_SKEL = resolve(ASSET_DIR, 'spineboy-pro.json');
const ATLAS = resolve(ASSET_DIR, 'spineboy.atlas');
const PMA_ATLAS = resolve(ASSET_DIR, 'spineboy-pma.atlas');
-const HAS_ASSETS = existsSync(SPINE43_WASM) && existsSync(SKEL);
+const HAS_ASSETS = hasSideModule('spine43') && existsSync(SKEL);
interface Batch {
vertexCount: number;
diff --git a/sdk/tests/videodec-module.test.ts b/sdk/tests/videodec-module.test.ts
index 951ec0e47..3a0c60b04 100644
--- a/sdk/tests/videodec-module.test.ts
+++ b/sdk/tests/videodec-module.test.ts
@@ -6,14 +6,14 @@
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'fs';
import { resolve } from 'path';
-import { WASM_DIR } from './helpers/loadWasm';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import type { VideoWasmModule } from '../src/video/WasmVideoBackend';
const GLUE = resolve(WASM_DIR, 'videodec.js');
const BINARY = resolve(WASM_DIR, 'videodec.wasm');
const FIXTURE = resolve(__dirname, 'fixtures/rgb-64x32.esv');
const FLIP_FIXTURE = resolve(__dirname, 'fixtures/topwhite-64x32.esv');
-const HAS_VIDEODEC = existsSync(BINARY);
+const HAS_VIDEODEC = hasSideModule('videodec');
const W = 64, H = 32;
diff --git a/sdk/tests/wasm-environment.test.ts b/sdk/tests/wasm-environment.test.ts
new file mode 100644
index 000000000..77c8a9a83
--- /dev/null
+++ b/sdk/tests/wasm-environment.test.ts
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file wasm-environment.test.ts — a skip has to mean "not applicable".
+ *
+ * @details It also meant "I could not reach the thing this needs", and the two
+ * read identically in a summary: one invocation reported 5110 passed
+ * and 309 skipped with no failures, while 43 suites had not run.
+ *
+ * So the corpus is decided in ONE place. These hold that place to it:
+ * every suite asks the shared helper rather than deciding for itself
+ * from the filesystem, and a run with no engine build has to say so
+ * instead of being inferred into.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { HAS_WASM, NO_WASM_MODE, SIDE_MODULES, WASM_DIR, hasSideModule } from './helpers/loadWasm';
+
+const TESTS = __dirname;
+
+describe('what decides whether the boundary suites run', () => {
+ it('is a declaration, not a guess about the filesystem', () => {
+ expect(HAS_WASM).toBe(!NO_WASM_MODE);
+ });
+
+ it('turns the whole corpus off with one flag', () => {
+ for (const name of SIDE_MODULES) {
+ if (NO_WASM_MODE) expect(hasSideModule(name), `${name} survived no-wasm mode`).toBe(false);
+ else expect(hasSideModule(name)).toBe(existsSync(resolve(WASM_DIR, `${name}.wasm`)));
+ }
+ });
+
+ it('is asked by every suite, rather than re-decided by each one', () => {
+ // A suite computing its own `existsSync(<module>.wasm)` is out of reach
+ // of both the declared profile and any central guarantee.
+ const offenders: string[] = [];
+ for (const file of readdirSync(TESTS)) {
+ if (!file.endsWith('.test.ts') || file === 'wasm-environment.test.ts') continue;
+ const text = readFileSync(resolve(TESTS, file), 'utf8');
+ for (const m of text.matchAll(/existsSync\(\s*([A-Za-z0-9_]+)\s*\)/g)) {
+ const declared = new RegExp(`const ${m[1]}\\b[^\\n]*\\.wasm`).test(text);
+ if (declared) offenders.push(`${file} → existsSync(${m[1]})`);
+ }
+ }
+ expect(offenders, 'a suite decides for itself whether the engine is available')
+ .toEqual([]);
+ });
+});
diff --git a/sdk/vitest.config.ts b/sdk/vitest.config.ts
index 4a1f43158..122397f18 100644
--- a/sdk/vitest.config.ts
+++ b/sdk/vitest.config.ts
@@ -8,6 +8,9 @@ export default defineConfig({
globals: true,
environment: 'happy-dom',
setupFiles: ['tests/setup.ts'],
+ // Proves the engine build is REACHABLE before anything collects, so an
+ // unavailable one fails rather than skipping. See globalSetup.ts.
+ globalSetup: ['tests/globalSetup.ts'],
include: ['tests/**/*.test.ts'],
// The soak suite judges heap growth, and a heap nobody can collect only
// climbs. Without this the census downgrades its heap counters to
diff --git a/tools/run-gates.mjs b/tools/run-gates.mjs
index 87037b2ee..7fa546e97 100644
--- a/tools/run-gates.mjs
+++ b/tools/run-gates.mjs
@@ -58,6 +58,11 @@ if (argv.includes('--plan')) {
function reportSuites() {
const suites = gates.filter((g) => g.covers?.length);
if (suites.length) console.log(` test suites run: ${suites.map((g) => g.id).join(', ')}`);
+ // A declared profile narrows what a suite covered, and the summary is where
+ // that has to be said — otherwise "green" quietly means "green minus 300".
+ if (process.env.SDK_TEST_MODE === 'no-wasm') {
+ console.log(' SDK_TEST_MODE=no-wasm — sdk-tests did NOT cover the engine boundary');
+ }
const unrun = noEditor.filter((g) => g.covers?.length);
if (unrun.length) {
console.log(` test suites NOT run: ${unrun.map((g) => g.id).join(', ')} — no editor checkout`);