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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(tests): a registry that was not the engine's, and a buffer count standing in for an invariant
esengine6bd59cef78ca
diff --git a/sdk/tests/README.md b/sdk/tests/README.mdindex aae197c93..f0d64c9bc 100644--- a/sdk/tests/README.md+++ b/sdk/tests/README.md@@ -17,47 +17,35 @@ zero: no new diagnostics, and fixed ones must be banked so they cannot return.The networking suites (`net-*`, `replication*`, `websocket`) carry **no** debtand `--update` refuses to add any.-## Known debt--### `airborne.test.ts`: the shared setup clears engine components--Two of its cases (`tilts about X, which every ground clip leaves alone` and-`is far enough from every other shipped pose to be told apart`) fail under this-package's vitest config and pass under the repo root's — **the same single file,-the same code, no other test running**:--```bash-npx vitest run sdk/tests/airborne.test.ts # from the repo root: 10 passed-cd sdk && npx vitest run tests/airborne.test.ts # 2 failed-```--So this is **not** order dependence, and not cross-file state leakage. It was-first recorded as "order-dependent in full-suite runs"; that reading came from-comparing a root-config run against a package-config run and reading the-difference as isolation. Bisecting the config difference names the trigger-exactly: with `setupFiles: ['tests/setup.ts']` removed and everything else-identical, the file passes 10/10.--`tests/setup.ts` runs `clearUserComponents()` before every test. Engine-components — animation, timeline, AI, audio, physics joints, UI text, tilemap —-`defineComponent` at SDK module load into the **same per-app user registry** a-project's own components use (see the comment above `markEngineComponentBaseline`-in `src/ecs/component.ts`). Clearing it drops those too, with nothing to put them-back, so the animator writes nothing into the joint and the sampled pose stays-identity — which is a pose no clip can be told apart from.--**The obvious one-line fix does not work.** `seedEngineComponents()` exists for-exactly this, but it is a no-op until `markEngineComponentBaseline()` has run,-and setup files execute *before* the test file's imports — so at setup time the-engine components this file needs are not registered yet and there is nothing to-snapshot. Any fix has to establish the baseline after collection (the first-`beforeEach` is the earliest such point) and reseed after each clear, which-changes the component-registry lifetime for all 509 test files. That deserves its-own change with a full-suite before/after, not a patch here.--**Widening the assertions, retrying, or pinning execution order are not fixes** —-they hide a registry lifetime bug that makes some other suite's green-untrustworthy too.+## The component registry, per test++`setup.ts` clears the per-app user component registry before every test, so one+test's `defineComponent` cannot decide another's. It used to clear it to EMPTY,+and that was wrong in a way nothing reported.++Engine components — animation, timeline, AI, audio, joints, UI text, tilemap —+`defineComponent` at SDK module load into that same registry (see the comment+above `markEngineComponentBaseline` in `src/ecs/component.ts`). A module body+runs once, so a clear took them out with nothing to put them back. The result+was never an error: an animator wrote nothing into its joint and the sampled+pose stayed identity, which is a pose no clip can be told apart from. Two cases+in `airborne.test.ts` failed on exactly that; a golden of "every builtin with+field metadata" was silently missing `Marker`.++The setup now snapshots the registry at the FIRST `beforeEach` and reseeds after+each clear. The timing is forced, and the obvious one-liner does not work: a+setup file's body runs before the file under test is imported, with 25 of the+engine's 65 components registered — `markEngineComponentBaseline()` there loses+the other 40, which is a partial restore that looks like a fix. The first+`beforeEach` is the earliest point at which the file's own imports have run.++`harness-component-registry.test.ts` holds both halves, and names `Animator`+(registered by a module only the test file imports) beside `Marker` (registered+by one the setup file imports) so a setup-load snapshot fails it.++**Widening the assertions, retrying, or pinning execution order would not have+been fixes** — they hide a registry lifetime bug that makes some other suite's+green untrustworthy too.## Running Testsdiff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex 7b7f075f8..081be7fd7 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -354,6 +354,11 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"tooltip": "Point, Directional, Ambient, or Spot.",},},+ "Marker": {+ "properties": {+ "map": true,+ },+ },"MeshRenderer": {"color": {"tooltip": "Tint multiplied into the vertex colors (white = unchanged).",diff --git a/sdk/tests/airborne.test.ts b/sdk/tests/airborne.test.tsindex 6a5fc0a06..bedc36816 100644--- a/sdk/tests/airborne.test.ts+++ b/sdk/tests/airborne.test.ts@@ -3,10 +3,6 @@/*** The claim: a character off the ground stops looking like one standing on it.* Through the SHIPPED graph and clip — a fixture pair proves nothing about them.- *- * Two cases here fail under this package's vitest config and pass under the repo- * root's, because the shared `tests/setup.ts` clears engine components. See- * "Known debt" in `sdk/tests/README.md`.*/import { describe, it, expect } from 'vitest';import { readFileSync } from 'node:fs';diff --git a/sdk/tests/component-fieldmeta-golden.test.ts b/sdk/tests/component-fieldmeta-golden.test.tsindex 46ed96c2a..9c98f69e4 100644--- a/sdk/tests/component-fieldmeta-golden.test.ts+++ b/sdk/tests/component-fieldmeta-golden.test.ts@@ -8,6 +8,10 @@ import { getComponentRegistry, getComponentFieldMeta } from '../src/ecs/componen// hand-written component.ts overlay into generated COMPONENT_META.fields. That// migration changes the *source* of these values, never the values themselves —// this snapshot fails if any field's resolved metadata drifts during the move.+//+// It reads the LIVE registry, so it is a snapshot of the engine only while the+// harness leaves the engine's own components in it — `Marker` was absent here+// for as long as the shared setup cleared them.describe('builtin FieldMeta (RC9-1 equivalence gate)', () => {it('matches the golden snapshot of every builtin with declared field metadata', () => {const names = [...getComponentRegistry().keys()].sort();diff --git a/sdk/tests/harness-component-registry.test.ts b/sdk/tests/harness-component-registry.test.tsnew file mode 100644index 000000000..7739d1ed2--- /dev/null+++ b/sdk/tests/harness-component-registry.test.ts@@ -0,0 +1,38 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file What the shared setup owes every test: an isolated registry that is+ * still the engine's.+ *+ * Both halves matter and they pull against each other. Clearing to empty took+ * engine components out too, and nothing re-registers a module body — the+ * result was an identity pose and an unwritten joint, which is what an+ * assertion cannot tell from a correct answer. Not clearing at all would let+ * one test's components decide another's.+ */+import { describe, it, expect } from 'vitest';+import { defineComponent, getComponent } from '../src/ecs/component';+// Imported for its module-level registrations, which is the whole point: they+// happen at COLLECTION, after the setup file's own body has already run.+import '../src/animation';++const LEAKED = 'HarnessLeakCanary';++describe('the shared test setup', () => {+ it('leaves engine components registered, because a module body runs once', () => {+ // Marker registers from ecs/component, which the setup file imports+ // itself; Animator from a module only the file under test pulls in. A+ // baseline taken at setup load keeps the first and loses 40 of the other.+ expect(getComponent('Marker')).toBeDefined();+ expect(getComponent('Animator')).toBeDefined();+ });++ it('registers one for the next case to look for', () => {+ defineComponent(LEAKED, { n: 0 });+ expect(getComponent(LEAKED)).toBeDefined();+ });++ it('does not carry one test\'s components into the next', () => {+ expect(getComponent(LEAKED)).toBeUndefined();+ });+});diff --git a/sdk/tests/renderer.test.ts b/sdk/tests/renderer.test.tsindex cc12df335..0281505af 100644--- a/sdk/tests/renderer.test.ts+++ b/sdk/tests/renderer.test.ts@@ -85,23 +85,30 @@ describe('Renderer API', () => {// initRendererAPI / shutdownRendererAPI// =========================================================================+ // The mock returns the size as the pointer, so each buffer is its own value.+ const allocated = (): number[] => mock._malloc.mock.results.map((r) => r.value as number);+ const freed = (): number[] => mock._free.mock.calls.map((c) => c[0] as number);+describe('initRendererAPI', () => {- it('should allocate viewProjection buffer (16 * 4 = 64 bytes)', () => {- expect(mock._malloc).toHaveBeenCalledTimes(1);+ it('should allocate a viewProjection buffer (16 * 4 = 64 bytes)', () => {expect(mock._malloc).toHaveBeenCalledWith(64);});});describe('shutdownRendererAPI', () => {- it('should free viewProjection buffer', () => {+ // Every reader that marshals through the heap takes a buffer here. A+ // COUNT has to be rewritten each time one is added, which is how it comes+ // to be updated rather than read; the invariant does not move.+ it('gives back every scratch buffer it took, and takes nothing else', () => {shutdownRendererAPI();- expect(mock._free).toHaveBeenCalledTimes(1);+ expect([...freed()].sort()).toEqual([...allocated()].sort());});it('should handle double shutdown gracefully', () => {shutdownRendererAPI();+ const once = freed().length;shutdownRendererAPI();- expect(mock._free).toHaveBeenCalledTimes(1);+ expect(freed()).toHaveLength(once);});});diff --git a/sdk/tests/setup.ts b/sdk/tests/setup.tsindex 2bf446298..9ec8be8a9 100644--- a/sdk/tests/setup.ts+++ b/sdk/tests/setup.ts@@ -1,8 +1,34 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file setup.ts — each test starts with the registry the SDK left it, minus+ * whatever the previous test registered.+ *+ * Clearing to EMPTY was wrong, and quietly so. Engine components (animation,+ * timeline, AI, audio, joints, UI text, tilemap) `defineComponent` at module+ * load into the same per-app user registry a project's own use, and a module+ * body runs once — so a clear takes them out with nothing to put them back.+ * What follows is not a failure but an identity pose, an unwritten joint, a+ * query that matches nothing: the shapes an assertion cannot tell from a+ * correct answer.+ *+ * The snapshot has to be taken HERE and not at module load: a setup file's body+ * runs before the file under test is imported, with 25 of the engine's 65+ * components registered — the rest arrive with that file's own imports, and the+ * first beforeEach is the earliest point at which they have.+ */import { beforeEach } from 'vitest';-import { clearUserComponents } from '../src/ecs/component';+import {+ clearUserComponents, markEngineComponentBaseline, seedEngineComponents,+} from '../src/ecs/component';++let baselineTaken = false;beforeEach(() => {+ if (!baselineTaken) {+ markEngineComponentBaseline();+ baselineTaken = true;+ }clearUserComponents();+ seedEngineComponents();});