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.

test(sdk): mock-wasm App harness; FocusPlugin builtin branches covered

yhha05e498fd1ac
diff --git a/sdk/tests/helpers/mockApp.ts b/sdk/tests/helpers/mockApp.ts
new file mode 100644
index 000000000..b376cb4e2
--- /dev/null
+++ b/sdk/tests/helpers/mockApp.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Boot an App wired to the JS-backed mock wasm module (tests/mocks/wasm).
+ * This is the lightweight harness for TS-side plugin logic: the full ECS
+ * works — including wasm-backed BUILTIN components, whose field data the
+ * mock stores in plain JS — with no native binary to build or load.
+ *
+ * What the mock does NOT do is run any wasm-side computation (physics
+ * stepping, layout solves, rendering). Use this to assert the TS wiring a
+ * plugin owns — component defaults, registration, reconcile decisions,
+ * system orchestration, event emission — and leave the native simulation
+ * to the *-smoke.mjs runners that link the real engine.
+ */
+import { App } from '../../src/app';
+import { AppContext, setDefaultContext } from '../../src/context';
+import { setEditorMode, setPlayMode } from '../../src/env';
+import { createMockModule } from '../mocks/wasm';
+import type { ESEngineModule } from '../../src/wasm';
+
+export interface MockApp {
+ app: App;
+ module: ESEngineModule;
+}
+
+/**
+ * A fresh App connected to a mock wasm module. Resets the component/system
+ * registry (AppContext) and puts the process in standalone play mode so that
+ * `playModeOnly()` gameplay systems actually run. Call once per test for
+ * isolation; each call starts from a clean registry.
+ */
+export function bootMockApp(): MockApp {
+ setDefaultContext(new AppContext()); // isolate component/system registration per test
+ setEditorMode(false);
+ setPlayMode(false); // standalone runtime ⇒ playModeOnly() === true
+ const app = App.new();
+ const module = createMockModule();
+ app.world.connectCpp(module.getRegistry(), module);
+ return { app, module };
+}
diff --git a/sdk/tests/ui-focus-plugin.test.ts b/sdk/tests/ui-focus-plugin.test.ts
index e9c330db1..15bd35aa9 100644
--- a/sdk/tests/ui-focus-plugin.test.ts
+++ b/sdk/tests/ui-focus-plugin.test.ts
@@ -1,109 +1,132 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file The keyboard-focus plugin's Tab navigation, exercised through a real
- * App. App.new() runs the JS-side ECS with no wasm, so this is the
- * lightweight plugin test path: build the plugin onto a fresh app, drive
- * the Input resource, tick, assert world/resource state. FocusSystem is
- * playModeOnly, the default for a standalone runtime.
- *
- * Scope note: Focusable is a JS-backed defineComponent, so its tabIndex
- * drives navigation here. Interactable/UIInteraction are wasm-backed
- * builtins (BuiltinBridge) — their fields (enabled gating, justPressed
- * click-focus) can't be set without a connected wasm module, so those two
- * branches belong to a wasm-harness pass, not this one.
+ * @file FocusPlugin's keyboard + pointer focus, driven through a mock-wasm App
+ * (see tests/helpers/mockApp). The mock backs the builtin Interactable /
+ * UIInteraction fields in JS, so the enabled-gating and click-to-focus
+ * branches — unreachable without a connected module — are covered here
+ * alongside the pure Tab navigation. FocusSystem is playModeOnly, which
+ * the harness satisfies.
*/
import { describe, it, expect, beforeEach } from 'vitest';
-import { App, flushPendingSystems } from '../src/app';
-import { AppContext, setDefaultContext } from '../src/context';
-import { setEditorMode, setPlayMode } from '../src/env';
+import { flushPendingSystems } from '../src/app';
+import type { App } from '../src/app';
import { Input, InputState } from '../src/input';
import { UIEvents, UIEventQueue } from '../src/ui/core/events';
import { Focusable, FocusManager } from '../src/ui/input/focusable';
+import { Interactable, UIInteraction } from '../src/ui/input/interactable';
import { focusPlugin } from '../src/ui/input/focus';
+import { bootMockApp } from './helpers/mockApp';
import type { Entity } from '../src/types';
-beforeEach(() => {
- setDefaultContext(new AppContext()); // isolate component/system registration per test
- setEditorMode(false);
- setPlayMode(false); // standalone runtime ⇒ playModeOnly() true ⇒ FocusSystem runs
-});
+let app: App;
-function makeApp(): App {
- const app = App.new();
- app.insertResource(Input, new InputState());
+beforeEach(() => {
+ app = bootMockApp().app;
+ app.insertResource(Input, new InputState()); // fresh, so key state can't leak between tests
app.insertResource(UIEvents, new UIEventQueue());
focusPlugin.build(app); // registers Focusable, inserts a fresh FocusManager, adds FocusSystem
flushPendingSystems(app);
- return app;
-}
+});
-function addFocusable(app: App, tabIndex: number): Entity {
+/** A focusable entity. `enabled` drives the (builtin) Interactable gate. */
+function addFocusable(tabIndex: number, enabled = true): Entity {
const e = app.world.spawn();
app.world.insert(e, Focusable, { tabIndex, isFocused: false });
+ app.world.insert(e, Interactable, { enabled });
return e;
}
-async function tab(app: App, opts: { shift?: boolean } = {}): Promise<void> {
+async function tab(opts: { shift?: boolean } = {}): Promise<void> {
const input = app.getResource(Input) as InputState;
input.keysPressed.add('Tab');
if (opts.shift) input.keysDown.add('Shift');
await app.tick(1 / 60);
- input.keysPressed.delete('Tab'); // tick clears keysPressed anyway; explicit for clarity
+ input.keysPressed.delete('Tab');
if (opts.shift) input.keysDown.delete('Shift');
}
-const focused = (app: App): Entity | null => app.getResource(FocusManager).focusedEntity;
-const isFocused = (app: App, e: Entity): boolean =>
+const focused = (): Entity | null => app.getResource(FocusManager).focusedEntity;
+const isFocused = (e: Entity): boolean =>
(app.world.get(e, Focusable) as { isFocused: boolean }).isFocused;
describe('FocusPlugin Tab navigation', () => {
it('focuses the lowest tabIndex first, then advances in tabIndex order', async () => {
- const app = makeApp();
- const b = addFocusable(app, 20); // inserted first, but higher tabIndex
- const a = addFocusable(app, 10);
- const c = addFocusable(app, 30);
-
- await tab(app);
- expect(focused(app)).toBe(a); // sorted by tabIndex, not spawn order
- expect(isFocused(app, a)).toBe(true);
-
- await tab(app);
- expect(focused(app)).toBe(b);
- expect(isFocused(app, a)).toBe(false); // the previous entity is blurred
- expect(isFocused(app, b)).toBe(true);
-
- await tab(app);
- expect(focused(app)).toBe(c);
+ const b = addFocusable(20); // inserted first, but higher tabIndex
+ const a = addFocusable(10);
+ const c = addFocusable(30);
+
+ await tab();
+ expect(focused()).toBe(a); // sorted by tabIndex, not spawn order
+ expect(isFocused(a)).toBe(true);
+
+ await tab();
+ expect(focused()).toBe(b);
+ expect(isFocused(a)).toBe(false); // previous entity blurred
+ expect(isFocused(b)).toBe(true);
+
+ await tab();
+ expect(focused()).toBe(c);
});
it('wraps from the last focusable back to the first', async () => {
- const app = makeApp();
- const a = addFocusable(app, 0);
- addFocusable(app, 1);
- await tab(app); // → a
- await tab(app); // → second
- await tab(app); // → wraps back to a
- expect(focused(app)).toBe(a);
+ const a = addFocusable(0);
+ addFocusable(1);
+ await tab(); // → a
+ await tab(); // → second
+ await tab(); // → wraps to a
+ expect(focused()).toBe(a);
});
it('Shift+Tab walks the order in reverse, starting from the last entry', async () => {
- const app = makeApp();
- const a = addFocusable(app, 0);
- const b = addFocusable(app, 1);
- await tab(app, { shift: true }); // no current focus + reverse ⇒ last
- expect(focused(app)).toBe(b);
- await tab(app, { shift: true });
- expect(focused(app)).toBe(a);
+ const a = addFocusable(0);
+ const b = addFocusable(1);
+ await tab({ shift: true }); // no current focus + reverse ⇒ last
+ expect(focused()).toBe(b);
+ await tab({ shift: true });
+ expect(focused()).toBe(a);
});
- it('re-focusing the already-focused entity is a no-op (no redundant blur/focus churn)', async () => {
- const app = makeApp();
- const only = addFocusable(app, 0);
- await tab(app);
- expect(focused(app)).toBe(only);
- await tab(app); // single focusable ⇒ cycles back to itself
- expect(focused(app)).toBe(only);
- expect(isFocused(app, only)).toBe(true);
+ it('re-focusing the already-focused entity is a no-op', async () => {
+ const only = addFocusable(0);
+ await tab();
+ await tab(); // single focusable ⇒ stays on itself
+ expect(focused()).toBe(only);
+ expect(isFocused(only)).toBe(true);
+ });
+
+ it('skips a focusable whose Interactable is disabled', async () => {
+ const a = addFocusable(0);
+ addFocusable(1, /* enabled */ false); // out of the tab order
+ const c = addFocusable(2);
+ await tab();
+ expect(focused()).toBe(a);
+ await tab();
+ expect(focused()).toBe(c); // jumps over the disabled one
+ });
+});
+
+describe('FocusPlugin pointer focus', () => {
+ it('a justPressed UIInteraction focuses that entity', async () => {
+ const e = app.world.spawn();
+ app.world.insert(e, Focusable, { tabIndex: 0, isFocused: false });
+ app.world.insert(e, UIInteraction, { justPressed: true });
+ await app.tick(1 / 60);
+ expect(focused()).toBe(e);
+ expect(isFocused(e)).toBe(true);
+ });
+
+ it('moving focus by click blurs the previously focused entity', async () => {
+ const a = addFocusable(0);
+ await tab();
+ expect(focused()).toBe(a);
+
+ const b = app.world.spawn();
+ app.world.insert(b, Focusable, { tabIndex: 5, isFocused: false });
+ app.world.insert(b, UIInteraction, { justPressed: true });
+ await app.tick(1 / 60);
+ expect(focused()).toBe(b);
+ expect(isFocused(a)).toBe(false); // a was blurred
+ expect(isFocused(b)).toBe(true);
});
});