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(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.md
index 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** debt
and `--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 Tests
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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();
});