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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, vi, afterEach } from 'vitest';
import { StatsCollector, defaultFrameStats, Stats, StatsPlugin, statsPlugin, FrameHistory, type FrameStats } from '../src/stats';
import { StatsOverlay } from '../src/stats-overlay';
import { App } from '../src/app/app';
import { Schedule, defineSystem, SystemRunner } from '../src/ecs/system';
import { World } from '../src/ecs/world';
import { ResourceStorage } from '../src/ecs/resource';
import * as rendererModule from '../src/render/renderer';
afterEach(() => {
vi.restoreAllMocks();
});
// ============================================================================
// StatsCollector
// ============================================================================
describe('StatsCollector', () => {
it('should start with 0 FPS and 0 frame time', () => {
const collector = new StatsCollector();
expect(collector.getFps()).toBe(0);
expect(collector.getFrameTimeMs()).toBe(0);
});
it('should calculate FPS from delta seconds', () => {
const collector = new StatsCollector();
for (let i = 0; i < 10; i++) {
collector.pushFrame(1 / 60);
}
expect(collector.getFps()).toBeCloseTo(60, 0);
});
it('should calculate frame time in milliseconds', () => {
const collector = new StatsCollector();
for (let i = 0; i < 10; i++) {
collector.pushFrame(1 / 60);
}
expect(collector.getFrameTimeMs()).toBeCloseTo(16.67, 0);
});
it('should use sliding window of 60 frames', () => {
const collector = new StatsCollector();
for (let i = 0; i < 60; i++) {
collector.pushFrame(1 / 30);
}
expect(collector.getFps()).toBeCloseTo(30, 0);
for (let i = 0; i < 60; i++) {
collector.pushFrame(1 / 120);
}
expect(collector.getFps()).toBeCloseTo(120, 0);
});
it('should handle zero delta gracefully', () => {
const collector = new StatsCollector();
collector.pushFrame(0);
expect(collector.getFps()).toBe(0);
expect(collector.getFrameTimeMs()).toBe(0);
});
it('should handle very large delta', () => {
const collector = new StatsCollector();
collector.pushFrame(1);
expect(collector.getFps()).toBeCloseTo(1, 0);
expect(collector.getFrameTimeMs()).toBeCloseTo(1000, 0);
});
it('should average across partial window', () => {
const collector = new StatsCollector();
collector.pushFrame(1 / 60);
collector.pushFrame(1 / 60);
collector.pushFrame(1 / 60);
expect(collector.getFps()).toBeCloseTo(60, 0);
});
it('should converge to new rate after window fills', () => {
const collector = new StatsCollector();
for (let i = 0; i < 60; i++) collector.pushFrame(1 / 60);
expect(collector.getFps()).toBeCloseTo(60, 0);
for (let i = 0; i < 30; i++) collector.pushFrame(1 / 30);
const fps = collector.getFps();
expect(fps).toBeLessThan(60);
expect(fps).toBeGreaterThan(30);
});
it('should maintain accuracy with > 100 frames pushed', () => {
const collector = new StatsCollector();
for (let i = 0; i < 200; i++) {
collector.pushFrame(1 / 144);
}
expect(collector.getFps()).toBeCloseTo(144, 0);
expect(collector.getFrameTimeMs()).toBeCloseTo(1000 / 144, 0);
});
// === Review fix: Critical #1 — negative/NaN/Infinity delta ===
it('should clamp negative delta to 0', () => {
const collector = new StatsCollector();
for (let i = 0; i < 10; i++) collector.pushFrame(1 / 60);
collector.pushFrame(-0.5);
const fps = collector.getFps();
expect(fps).toBeGreaterThanOrEqual(0);
expect(Number.isFinite(fps)).toBe(true);
});
it('should ignore NaN delta', () => {
const collector = new StatsCollector();
for (let i = 0; i < 10; i++) collector.pushFrame(1 / 60);
collector.pushFrame(NaN);
expect(Number.isFinite(collector.getFps())).toBe(true);
expect(collector.getFps()).toBeCloseTo(60, 0);
});
it('should ignore Infinity delta', () => {
const collector = new StatsCollector();
for (let i = 0; i < 10; i++) collector.pushFrame(1 / 60);
collector.pushFrame(Infinity);
expect(Number.isFinite(collector.getFps())).toBe(true);
expect(collector.getFps()).toBeCloseTo(60, 0);
});
// === Review fix: Critical #2 — float drift sum_ <= 0 ===
it('should never return negative FPS from float drift', () => {
const collector = new StatsCollector();
for (let i = 0; i < 200; i++) {
collector.pushFrame(0);
}
expect(collector.getFps()).toBe(0);
expect(collector.getFrameTimeMs()).toBe(0);
});
});
// ============================================================================
// defaultFrameStats
// ============================================================================
describe('defaultFrameStats', () => {
it('should initialize all numeric fields to 0', () => {
const stats = defaultFrameStats();
expect(stats.fps).toBe(0);
expect(stats.frameTimeMs).toBe(0);
expect(stats.entityCount).toBe(0);
expect(stats.drawCalls).toBe(0);
expect(stats.triangles).toBe(0);
expect(stats.sprites).toBe(0);
expect(stats.text).toBe(0);
expect(stats.skeletal).toBe(0);
expect(stats.meshes).toBe(0);
expect(stats.culled).toBe(0);
});
it('should initialize systemTimings as empty Map', () => {
const stats = defaultFrameStats();
expect(stats.systemTimings).toBeInstanceOf(Map);
expect(stats.systemTimings.size).toBe(0);
});
it('should return independent instances', () => {
const a = defaultFrameStats();
const b = defaultFrameStats();
a.fps = 60;
a.systemTimings.set('x', 1);
expect(b.fps).toBe(0);
expect(b.systemTimings.size).toBe(0);
});
});
// ============================================================================
// App stats API
// ============================================================================
describe('App stats API', () => {
it('should return null timings before enableStats', () => {
const app = App.new();
expect(app.getSystemTimings()).toBeNull();
});
it('should return timings map after enableStats + tick', async () => {
const app = App.new();
app.enableStats();
await app.tick(1 / 60);
expect(app.getSystemTimings()).toBeInstanceOf(Map);
});
it('should record named system timings after enableStats', async () => {
const app = App.new();
app.enableStats();
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => {}, { name: 'MySystem' }
));
await app.tick(1 / 60);
const timings = app.getSystemTimings()!;
expect(timings.has('MySystem')).toBe(true);
expect(typeof timings.get('MySystem')).toBe('number');
});
it('getFrameScopes is null before enableStats; measureFrameScope is a passthrough', () => {
const app = App.new();
expect(app.getFrameScopes()).toBeNull();
// Off = no map, so the scope runs but records nothing and returns the value.
expect(app.measureFrameScope('x', () => 42)).toBe(42);
expect(app.getFrameScopes()).toBeNull();
});
it('measureFrameScope records a named scope after enableStats', () => {
const app = App.new();
app.enableStats();
const out = app.measureFrameScope('render.resolveCameras', () => 'ok');
expect(out).toBe('ok');
const scopes = app.getFrameScopes()!;
expect(scopes).toBeInstanceOf(Map);
expect(typeof scopes.get('render.resolveCameras')).toBe('number');
expect(scopes.get('render.resolveCameras')).toBeGreaterThanOrEqual(0);
});
it('measureFrameScope accumulates repeats of the same name within a frame', () => {
const app = App.new();
app.enableStats();
app.measureFrameScope('dup', () => {});
const first = app.getFrameScopes()!.get('dup')!;
app.measureFrameScope('dup', () => {});
expect(app.getFrameScopes()!.get('dup')!).toBeGreaterThanOrEqual(first);
// Still a single accumulated entry, not two.
expect([...app.getFrameScopes()!.keys()].filter((k) => k === 'dup')).toHaveLength(1);
});
it('frame scopes reset at tick start', async () => {
const app = App.new();
app.enableStats();
app.measureFrameScope('stale', () => {});
expect(app.getFrameScopes()!.has('stale')).toBe(true);
await app.tick(1 / 60); // no system records 'stale' this frame
expect(app.getFrameScopes()!.has('stale')).toBe(false);
});
it('measureFrameScope still records when the body throws', () => {
const app = App.new();
app.enableStats();
expect(() => app.measureFrameScope('boom', () => { throw new Error('x'); })).toThrow('x');
expect(app.getFrameScopes()!.has('boom')).toBe(true);
});
it('should return entity count', () => {
const app = App.new();
expect(app.getEntityCount()).toBe(0);
app.world.spawn();
app.world.spawn();
expect(app.getEntityCount()).toBe(2);
});
it('should chain enableStats', () => {
const app = App.new();
expect(app.enableStats()).toBe(app);
});
it('should track entity count after despawn', () => {
const app = App.new();
const e1 = app.world.spawn();
app.world.spawn();
expect(app.getEntityCount()).toBe(2);
app.world.despawn(e1);
expect(app.getEntityCount()).toBe(1);
});
// === Review fix: Medium #4 — enableStats after first tick ===
it('should work when enableStats is called after first tick', async () => {
const app = App.new();
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => {}, { name: 'LateSystem' }
));
await app.tick(1 / 60);
expect(app.getSystemTimings()).toBeNull();
app.enableStats();
await app.tick(1 / 60);
const timings = app.getSystemTimings();
expect(timings).toBeInstanceOf(Map);
expect(timings!.has('LateSystem')).toBe(true);
});
});
// ============================================================================
// SystemRunner timing
// ============================================================================
describe('SystemRunner timing', () => {
function createRunner() {
const world = new World();
const resources = new ResourceStorage();
const runner = new SystemRunner(world, resources);
return { world, resources, runner };
}
it('should have timing disabled by default', () => {
const { runner } = createRunner();
expect(runner.getTimings()).toBeNull();
});
it('should enable timing and return empty map', () => {
const { runner } = createRunner();
runner.setTimingEnabled(true);
expect(runner.getTimings()).toBeInstanceOf(Map);
expect(runner.getTimings()!.size).toBe(0);
});
it('should record system execution time when enabled', () => {
const { runner } = createRunner();
runner.setTimingEnabled(true);
const system = defineSystem([], () => {
let sum = 0;
for (let i = 0; i < 1000; i++) sum += i;
}, { name: 'TestSystem' });
runner.run(system);
const timings = runner.getTimings()!;
expect(timings.has('TestSystem')).toBe(true);
expect(timings.get('TestSystem')).toBeGreaterThanOrEqual(0);
});
it('should not record timing when disabled', () => {
const { runner } = createRunner();
const system = defineSystem([], () => {}, { name: 'NoTimingSystem' });
runner.run(system);
expect(runner.getTimings()).toBeNull();
});
it('should record timings for multiple systems', () => {
const { runner } = createRunner();
runner.setTimingEnabled(true);
const systemA = defineSystem([], () => {}, { name: 'SystemA' });
const systemB = defineSystem([], () => {}, { name: 'SystemB' });
runner.run(systemA);
runner.run(systemB);
const timings = runner.getTimings()!;
expect(timings.has('SystemA')).toBe(true);
expect(timings.has('SystemB')).toBe(true);
});
it('should overwrite previous timing on re-run', () => {
const { runner } = createRunner();
runner.setTimingEnabled(true);
const system = defineSystem([], () => {}, { name: 'RerunSystem' });
runner.run(system);
runner.run(system);
expect(runner.getTimings()!.has('RerunSystem')).toBe(true);
expect(typeof runner.getTimings()!.get('RerunSystem')).toBe('number');
});
it('should disable timing and clear data', () => {
const { runner } = createRunner();
runner.setTimingEnabled(true);
const system = defineSystem([], () => {}, { name: 'ClearSystem' });
runner.run(system);
expect(runner.getTimings()!.size).toBeGreaterThan(0);
runner.setTimingEnabled(false);
expect(runner.getTimings()).toBeNull();
});
it('should still record timing when system throws', () => {
const { runner } = createRunner();
runner.setTimingEnabled(true);
const system = defineSystem([], () => {
throw new Error('boom');
}, { name: 'ThrowSystem' });
expect(() => runner.run(system)).toThrow('boom');
expect(runner.getTimings()!.has('ThrowSystem')).toBe(true);
});
});
// ============================================================================
// StatsPlugin integration
// ============================================================================
describe('StatsPlugin', () => {
it('should register Stats resource on build', () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
expect(app.hasResource(Stats)).toBe(true);
});
it('should enable system timings on the app', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
expect(app.getSystemTimings()).not.toBeNull();
});
it('should have name "Stats"', () => {
expect(new StatsPlugin().name).toBe('stats');
});
// === Review fix: Critical #3 — singleton reuse ===
it('should reset state when build is called on a new app', async () => {
const plugin = new StatsPlugin({ overlay: false });
const app1 = App.new();
app1.addPlugin(plugin);
for (let i = 0; i < 30; i++) await app1.tick(1 / 30);
expect(app1.getResource(Stats).fps).toBeCloseTo(30, 0);
plugin.cleanup();
const app2 = App.new();
app2.addPlugin(plugin);
for (let i = 0; i < 10; i++) await app2.tick(1 / 60);
const fps = app2.getResource(Stats).fps;
expect(fps).toBeCloseTo(60, 0);
});
describe('fps & frameTimeMs', () => {
it('should compute fps from delta', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
for (let i = 0; i < 10; i++) await app.tick(1 / 60);
const stats = app.getResource(Stats);
expect(stats.fps).toBeCloseTo(60, 0);
});
it('should compute frameTimeMs from delta', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
for (let i = 0; i < 5; i++) await app.tick(1 / 60);
const stats = app.getResource(Stats);
expect(stats.frameTimeMs).toBeCloseTo(16.67, 0);
});
it('should track changing frame rate', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
for (let i = 0; i < 60; i++) await app.tick(1 / 30);
expect(app.getResource(Stats).fps).toBeCloseTo(30, 0);
for (let i = 0; i < 60; i++) await app.tick(1 / 120);
expect(app.getResource(Stats).fps).toBeCloseTo(120, 0);
});
});
describe('entityCount', () => {
it('should reflect current entity count', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
app.world.spawn();
app.world.spawn();
app.world.spawn();
await app.tick(1 / 60);
expect(app.getResource(Stats).entityCount).toBe(3);
});
it('should update after spawn/despawn between ticks', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
const e1 = app.world.spawn();
app.world.spawn();
await app.tick(1 / 60);
expect(app.getResource(Stats).entityCount).toBe(2);
app.world.despawn(e1);
await app.tick(1 / 60);
expect(app.getResource(Stats).entityCount).toBe(1);
app.world.spawn();
app.world.spawn();
await app.tick(1 / 60);
expect(app.getResource(Stats).entityCount).toBe(3);
});
it('should be 0 with no entities', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
expect(app.getResource(Stats).entityCount).toBe(0);
});
});
describe('systemTimings', () => {
it('should contain named user systems', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => {}, { name: 'PhysicsSystem' }
));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => {}, { name: 'AnimationSystem' }
));
await app.tick(1 / 60);
const timings = app.getResource(Stats).systemTimings;
expect(timings.has('PhysicsSystem')).toBe(true);
expect(timings.has('AnimationSystem')).toBe(true);
});
it('should not include StatsCollect own timing on first tick', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
const timings = app.getResource(Stats).systemTimings;
expect(timings.has('StatsCollect')).toBe(false);
});
// === Review fix: Medium #8 — second tick leaks previous StatsCollect timing ===
it('should not include StatsCollect timing on subsequent ticks either', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
await app.tick(1 / 60);
await app.tick(1 / 60);
const timings = app.getResource(Stats).systemTimings;
expect(timings.has('StatsCollect')).toBe(false);
});
it('should record numeric timing values', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { let s = 0; for (let i = 0; i < 100; i++) s += i; },
{ name: 'WorkSystem' }
));
await app.tick(1 / 60);
const ms = app.getResource(Stats).systemTimings.get('WorkSystem');
expect(typeof ms).toBe('number');
expect(ms).toBeGreaterThanOrEqual(0);
});
it('should be a fresh Map copy (not shared reference)', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
const stats = app.getResource(Stats);
const ref1 = stats.systemTimings;
await app.tick(1 / 60);
const ref2 = stats.systemTimings;
expect(ref1).not.toBe(ref2);
});
});
describe('render stats from Renderer.getStats()', () => {
it('should copy all render stats fields', async () => {
const mockStats: rendererModule.RenderStats = {
drawCalls: 42, gpuDraws: 42, triangles: 8400, sprites: 100,
text: 12, skeletal: 3, meshes: 5, culled: 7,
};
vi.spyOn(rendererModule.Renderer, 'getStats').mockReturnValue(mockStats);
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
const stats = app.getResource(Stats);
expect(stats.drawCalls).toBe(42);
expect(stats.triangles).toBe(8400);
expect(stats.sprites).toBe(100);
expect(stats.text).toBe(12);
expect(stats.skeletal).toBe(3);
expect(stats.meshes).toBe(5);
expect(stats.culled).toBe(7);
});
it('should update render stats each tick', async () => {
const tick1: rendererModule.RenderStats = {
drawCalls: 10, gpuDraws: 10, triangles: 2000, sprites: 50,
text: 5, skeletal: 1, meshes: 2, culled: 3,
};
const tick2: rendererModule.RenderStats = {
drawCalls: 20, gpuDraws: 20, triangles: 4000, sprites: 80,
text: 8, skeletal: 2, meshes: 4, culled: 6,
};
const spy = vi.spyOn(rendererModule.Renderer, 'getStats');
spy.mockReturnValue(tick1);
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
let stats = app.getResource(Stats);
expect(stats.drawCalls).toBe(10);
expect(stats.sprites).toBe(50);
spy.mockReturnValue(tick2);
await app.tick(1 / 60);
stats = app.getResource(Stats);
expect(stats.drawCalls).toBe(20);
expect(stats.triangles).toBe(4000);
expect(stats.sprites).toBe(80);
expect(stats.text).toBe(8);
expect(stats.skeletal).toBe(2);
expect(stats.meshes).toBe(4);
expect(stats.culled).toBe(6);
});
it('should default to zeros when no WASM module', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin());
await app.tick(1 / 60);
const stats = app.getResource(Stats);
expect(stats.drawCalls).toBe(0);
expect(stats.triangles).toBe(0);
expect(stats.sprites).toBe(0);
expect(stats.text).toBe(0);
expect(stats.skeletal).toBe(0);
expect(stats.meshes).toBe(0);
expect(stats.culled).toBe(0);
});
});
describe('StatsPluginOptions', () => {
it('should accept overlay: false without creating DOM', async () => {
const plugin = new StatsPlugin({ overlay: false });
const app = App.new();
app.addPlugin(plugin);
await app.tick(1 / 60);
const stats = app.getResource(Stats);
expect(stats.fps).toBeGreaterThan(0);
});
it('should accept custom position', async () => {
const plugin = new StatsPlugin({ overlay: false, position: 'top-right' });
const app = App.new();
app.addPlugin(plugin);
await app.tick(1 / 60);
expect(app.hasResource(Stats)).toBe(true);
});
});
describe('cleanup', () => {
it('should be callable without error', async () => {
const plugin = new StatsPlugin({ overlay: false });
const app = App.new();
app.addPlugin(plugin);
await app.tick(1 / 60);
expect(() => plugin.cleanup()).not.toThrow();
});
it('should be safe to call cleanup multiple times', async () => {
const plugin = new StatsPlugin({ overlay: false });
const app = App.new();
app.addPlugin(plugin);
await app.tick(1 / 60);
plugin.cleanup();
expect(() => plugin.cleanup()).not.toThrow();
});
});
});
// ============================================================================
// StatsOverlay
// ============================================================================
describe('StatsOverlay', () => {
function makeStats(overrides: Partial<FrameStats> = {}): FrameStats {
return {
fps: 0, frameTimeMs: 0, entityCount: 0,
systemTimings: new Map(),
phaseTimings: new Map(),
drawCalls: 0, gpuDraws: 0, drawCallBudget: 0, triangles: 0, sprites: 0,
text: 0, skeletal: 0, meshes: 0, culled: 0,
...overrides,
};
}
it('should create a DOM element in the container', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
expect(container.children.length).toBe(1);
overlay.dispose();
});
it('should position bottom-left by default', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
const el = container.firstElementChild as HTMLElement;
expect(el.style.cssText).toContain('bottom');
expect(el.style.cssText).toContain('left');
overlay.dispose();
});
it('should position top-right when specified', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container, 'top-right');
const el = container.firstElementChild as HTMLElement;
expect(el.style.cssText).toContain('top');
expect(el.style.cssText).toContain('right');
overlay.dispose();
});
it('should display FPS value in update', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({ fps: 59.8 }));
expect(container.innerHTML).toContain('59.8');
overlay.dispose();
});
it('should display frameTimeMs value', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({ frameTimeMs: 16.7 }));
expect(container.innerHTML).toContain('16.7');
overlay.dispose();
});
it('should display drawCalls', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({ drawCalls: 42 }));
expect(container.innerHTML).toContain('42');
overlay.dispose();
});
it('should display triangles', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({ triangles: 8400 }));
expect(container.innerHTML).toContain('8400');
overlay.dispose();
});
it('should display sprites and culled', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({ sprites: 100, culled: 7 }));
const html = container.innerHTML;
expect(html).toContain('100');
expect(html).toContain('7');
overlay.dispose();
});
it('should display entityCount', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({ entityCount: 256 }));
expect(container.innerHTML).toContain('256');
overlay.dispose();
});
it('should display system timings sorted by cost', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({
systemTimings: new Map([
['Fast', 0.1],
['Slow', 5.0],
['Medium', 1.5],
]),
}));
const html = container.innerHTML;
const slowIdx = html.indexOf('Slow');
const medIdx = html.indexOf('Medium');
const fastIdx = html.indexOf('Fast');
expect(slowIdx).toBeLessThan(medIdx);
expect(medIdx).toBeLessThan(fastIdx);
overlay.dispose();
});
it('should limit to top 5 systems', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
const timings = new Map<string, number>();
for (let i = 0; i < 8; i++) {
timings.set(`System${i}`, i);
}
overlay.update(makeStats({ systemTimings: timings }));
const html = container.innerHTML;
expect(html).toContain('System7');
expect(html).toContain('System3');
expect(html).not.toContain('System2');
overlay.dispose();
});
it('should not render system section when empty', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats());
expect(container.innerHTML).not.toContain('Systems');
overlay.dispose();
});
it('should hide and show', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
const el = container.firstElementChild as HTMLElement;
overlay.hide();
expect(el.style.display).toBe('none');
overlay.update(makeStats({ fps: 60 }));
expect(el.innerHTML).toBe('');
overlay.show();
overlay.update(makeStats({ fps: 60 }));
expect(el.innerHTML).toContain('60');
overlay.dispose();
});
it('should remove element on dispose', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
expect(container.children.length).toBe(1);
overlay.dispose();
expect(container.children.length).toBe(0);
});
it('should truncate long system names', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({
systemTimings: new Map([
['VeryLongSystemNameThatExceedsTwenty', 1.0],
]),
}));
expect(container.innerHTML).toContain('...');
overlay.dispose();
});
// === Review fix: Medium #5 — XSS via system names ===
it('should escape HTML in system names', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({
systemTimings: new Map([
['<img src=x onerror=alert(1)>', 1.0],
]),
}));
const html = container.innerHTML;
expect(html).not.toContain('<img');
expect(html).toContain('<');
overlay.dispose();
});
// === Review fix: Medium #6 — padEnd spaces collapse in HTML ===
it('should preserve whitespace alignment in system names', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({
systemTimings: new Map([['Abc', 1.0]]),
}));
const el = container.firstElementChild as HTMLElement;
expect(el.style.cssText).toContain('white-space');
overlay.dispose();
});
// === Review fix: Low #11 — no-op after dispose ===
it('should not throw when update is called after dispose', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.dispose();
expect(() => overlay.update(makeStats({ fps: 60 }))).not.toThrow();
});
// === Throttle & avg/max ===
it('should render immediately on first update', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
overlay.update(makeStats({ fps: 60 }));
expect(container.innerHTML).toContain('60');
overlay.dispose();
});
it('should throttle DOM updates within the interval', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
let now = 1000;
vi.spyOn(performance, 'now').mockImplementation(() => now);
overlay.update(makeStats({ fps: 30, entityCount: 111 }));
expect(container.innerHTML).toContain('30');
expect(container.innerHTML).toContain('111');
now = 1100;
overlay.update(makeStats({ fps: 55, entityCount: 222 }));
expect(container.innerHTML).toContain('111');
expect(container.innerHTML).not.toContain('222');
overlay.dispose();
});
it('should render again after throttle interval elapses', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
let now = 1000;
vi.spyOn(performance, 'now').mockImplementation(() => now);
overlay.update(makeStats({ fps: 30 }));
expect(container.innerHTML).toContain('30');
now = 1600;
overlay.update(makeStats({ fps: 55 }));
expect(container.innerHTML).toContain('55');
overlay.dispose();
});
it('should display avg and max for system timings', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
let now = 1000;
vi.spyOn(performance, 'now').mockImplementation(() => now);
overlay.update(makeStats({
systemTimings: new Map([['Physics', 2.0]]),
}));
const html = container.innerHTML;
expect(html).toContain('Physics');
expect(html).toContain('2.0');
overlay.dispose();
});
it('should accumulate system timings across throttled frames and show avg/max', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
let now = 1000;
vi.spyOn(performance, 'now').mockImplementation(() => now);
overlay.update(makeStats({
systemTimings: new Map([['Physics', 1.0]]),
}));
now = 1100;
overlay.update(makeStats({
systemTimings: new Map([['Physics', 5.0]]),
}));
now = 1200;
overlay.update(makeStats({
systemTimings: new Map([['Physics', 1.0]]),
}));
now = 1600;
overlay.update(makeStats({
systemTimings: new Map([['Physics', 3.0]]),
}));
const html = container.innerHTML;
expect(html).toContain('Physics');
expect(html).toContain('3.0');
expect(html).toContain('5.0');
overlay.dispose();
});
it('should sort systems by max value', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
let now = 1000;
vi.spyOn(performance, 'now').mockImplementation(() => now);
overlay.update(makeStats({
systemTimings: new Map([['A', 0.5], ['B', 1.0]]),
}));
now = 1100;
overlay.update(makeStats({
systemTimings: new Map([['A', 10.0], ['B', 1.0]]),
}));
now = 1600;
overlay.update(makeStats({
systemTimings: new Map([['A', 0.5], ['B', 1.0]]),
}));
const html = container.innerHTML;
const aIdx = html.indexOf('A');
const bIdx = html.indexOf('B');
expect(aIdx).toBeLessThan(bIdx);
overlay.dispose();
});
it('should reset accumulator after rendering', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
let now = 1000;
vi.spyOn(performance, 'now').mockImplementation(() => now);
overlay.update(makeStats({
systemTimings: new Map([['Physics', 10.0]]),
}));
now = 1600;
overlay.update(makeStats({
systemTimings: new Map([['Physics', 1.0]]),
}));
const html = container.innerHTML;
expect(html).not.toContain('10.0');
expect(html).toContain('1.0');
overlay.dispose();
});
it('should render immediately after show() resets throttle', () => {
const container = document.createElement('div');
const overlay = new StatsOverlay(container);
let now = 1000;
vi.spyOn(performance, 'now').mockImplementation(() => now);
overlay.update(makeStats({ fps: 30 }));
expect(container.innerHTML).toContain('30');
overlay.hide();
now = 1050;
overlay.show();
overlay.update(makeStats({ fps: 45 }));
expect(container.innerHTML).toContain('45');
overlay.dispose();
});
});
// ============================================================================
// FrameHistory
// ============================================================================
describe('FrameHistory', () => {
it('should start empty', () => {
const history = new FrameHistory();
expect(history.count).toBe(0);
expect(history.getAll()).toEqual([]);
});
it('should store pushed snapshots', () => {
const history = new FrameHistory();
history.push(16.7, new Map([['Update', 5.0]]));
expect(history.count).toBe(1);
const all = history.getAll();
expect(all[0].frameTimeMs).toBeCloseTo(16.7);
expect(all[0].phaseTimings.get('Update')).toBe(5.0);
expect(all[0].systemTimings).toBeInstanceOf(Map);
expect(all[0].systemTimings.size).toBe(0);
});
it('should store systemTimings when provided', () => {
const history = new FrameHistory();
const sysTimes = new Map([['PhysicsSystem', 1.5], ['RenderSystem', 3.2]]);
history.push(16.7, new Map(), sysTimes);
const snap = history.getLatest()!;
expect(snap.systemTimings.get('PhysicsSystem')).toBe(1.5);
expect(snap.systemTimings.get('RenderSystem')).toBe(3.2);
});
it('should deep copy systemTimings on push', () => {
const history = new FrameHistory();
const sysTimes = new Map([['Sys', 2.0]]);
history.push(16.0, new Map(), sysTimes);
sysTimes.set('Sys', 99.0);
expect(history.getLatest()!.systemTimings.get('Sys')).toBe(2.0);
});
it('should preserve insertion order', () => {
const history = new FrameHistory();
history.push(10.0, new Map());
history.push(20.0, new Map());
history.push(30.0, new Map());
const all = history.getAll();
expect(all.map(s => s.frameTimeMs)).toEqual([10.0, 20.0, 30.0]);
});
it('should evict oldest when exceeding capacity', () => {
const capacity = 300;
const history = new FrameHistory(capacity);
for (let i = 0; i < capacity + 10; i++) {
history.push(i, new Map());
}
expect(history.count).toBe(capacity);
const all = history.getAll();
expect(all[0].frameTimeMs).toBe(10);
expect(all[all.length - 1].frameTimeMs).toBe(capacity + 9);
});
it('should return latest snapshot', () => {
const history = new FrameHistory();
history.push(10.0, new Map());
history.push(20.0, new Map());
expect(history.getLatest()!.frameTimeMs).toBe(20.0);
});
it('should return null for latest when empty', () => {
const history = new FrameHistory();
expect(history.getLatest()).toBeNull();
});
it('should use default capacity of 300', () => {
const history = new FrameHistory();
for (let i = 0; i < 400; i++) {
history.push(i, new Map());
}
expect(history.count).toBe(300);
});
it('should deep copy phase timings on push', () => {
const history = new FrameHistory();
const timings = new Map([['Update', 5.0]]);
history.push(16.0, timings);
timings.set('Update', 99.0);
expect(history.getLatest()!.phaseTimings.get('Update')).toBe(5.0);
});
it('should reset to empty', () => {
const history = new FrameHistory();
for (let i = 0; i < 10; i++) history.push(i, new Map());
expect(history.count).toBe(10);
history.reset();
expect(history.count).toBe(0);
expect(history.getAll()).toEqual([]);
});
});
// ============================================================================
// Phase Timings
// ============================================================================
describe('App phase timings', () => {
it('should return null before enableStats', () => {
const app = App.new();
expect(app.getPhaseTimings()).toBeNull();
});
it('should return a Map after enableStats + tick', async () => {
const app = App.new();
app.enableStats();
await app.tick(1 / 60);
const pt = app.getPhaseTimings();
expect(pt).toBeInstanceOf(Map);
});
it('should contain schedule phase names after tick', async () => {
const app = App.new();
app.enableStats();
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => {}, { name: 'Dummy' }
));
await app.tick(1 / 60);
const pt = app.getPhaseTimings()!;
expect(pt.has('First')).toBe(true);
expect(pt.has('PreUpdate')).toBe(true);
expect(pt.has('Update')).toBe(true);
expect(pt.has('PostUpdate')).toBe(true);
expect(pt.has('Last')).toBe(true);
});
it('should have numeric values for each phase', async () => {
const app = App.new();
app.enableStats();
await app.tick(1 / 60);
const pt = app.getPhaseTimings()!;
for (const [, v] of pt) {
expect(typeof v).toBe('number');
expect(v).toBeGreaterThanOrEqual(0);
}
});
it('should work when enableStats called after first tick', async () => {
const app = App.new();
await app.tick(1 / 60);
expect(app.getPhaseTimings()).toBeNull();
app.enableStats();
await app.tick(1 / 60);
expect(app.getPhaseTimings()).toBeInstanceOf(Map);
});
});
// ============================================================================
// FrameStats phaseTimings field
// ============================================================================
describe('FrameStats phaseTimings', () => {
it('should default to empty Map', () => {
const stats = defaultFrameStats();
expect(stats.phaseTimings).toBeInstanceOf(Map);
expect(stats.phaseTimings.size).toBe(0);
});
it('should be populated by StatsPlugin', async () => {
const app = App.new();
app.addPlugin(new StatsPlugin({ overlay: false }));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => {}, { name: 'TestSys' }
));
await app.tick(1 / 60);
const stats = app.getResource(Stats);
expect(stats.phaseTimings).toBeInstanceOf(Map);
expect(stats.phaseTimings.size).toBeGreaterThan(0);
});
});