Files
gods-eye-view/src/globe/contract.test.mjs
T
German Khokhlov b0cb8ce881 feat(globe): picks on input payloads
input.on('click'|'doubleClick'|'move', fn, { pick, drill }) delivers
{ …event, picked, drilled }: PickResult { id, owner, instance, primitive
(Cesium) } names the mover set (and instance) or line hit. One pick (and
one drill, as deep as the deepest listener) per event, shared by its
listeners; moves with picks are coalesced to one delivery per frame with
the latest position (src/globe/pickDelivery.js). Option checks in the
contract (normalizeInputOptions).

- Cesium: scene.pick / drillPick, and the picker names the owner: movers
  map billboards, points and models to their set and instance, lines
  their primitives to the line.
- Navara: a click with pick takes Navara's GPU pick of the same gesture
  (featureClick; its pick helper answers on the same pointerup, usually
  before the engine's click, so a fresh answer waits for it; otherwise
  the click waits up to 250 ms, then the CPU pick). Navara 0.2.1 answers
  clicks in quick succession with the first click's pick: a GPU answer
  whose instance is not drawn near the click is stale and the CPU pick
  answers. Hover, drill and the synchronous picker.pick/drillPick are CPU
  picks (src/globe/cpuPicks.js) of pickable mover sets and pickable lines
  (within half the width + 3 px), behind the globe excluded, nearest
  first; lines are picked on the CPU after an empty GPU answer.
  picker.clickStats() (Navara only) counts the answers and latencies.
- The fake engine picks its own movers and lines on the CPU unless
  scripted.
- The contract suite clicks with real pointer events (puppeteer) on both
  engines: a sprite is picked with its owner and instance, the map picks
  nothing, two sprites in one place drill both, a line is picked, a
  hover picks the sprite under it. Navara, 20 clicks: payload p50 2.8 ms,
  p95 4.1 ms after the click (puppeteer dispatch included), 20/20 GPU
  answers. The Cesium harness keeps the first-run card closed.
2026-10-16 18:25:12 +04:00

367 lines
12 KiB
JavaScript

import assert from 'node:assert/strict';
import test from 'node:test';
import {
ENGINE_KINDS,
GLOBE_ENGINE_MEMBERS,
INPUT_TYPES,
MODIFIERS,
SHARPEN_INITIAL,
assertGlobeEngine,
createEngineEvent,
isEngineEvent,
mergeSharpen,
} from './contract.js';
import { createFakeEngine } from './testing/fakeEngine.js';
import {
createContractSuite,
runContractSuite,
} from './testing/contractSuite.mjs';
test('engine event adds, raises and removes listeners in registration order', () => {
const event = createEngineEvent();
const seen = [];
const a = (value) => seen.push(['a', value]);
const b = (value) => seen.push(['b', value]);
const removeA = event.addEventListener(a);
event.addEventListener(b);
assert.equal(typeof removeA, 'function');
assert.equal(event.numberOfListeners, 2);
event.raiseEvent(1);
removeA();
event.raiseEvent(2);
assert.equal(event.removeEventListener(b), true);
assert.equal(event.removeEventListener(b), false);
event.raiseEvent(3);
assert.deepEqual(seen, [
['a', 1],
['b', 1],
['b', 2],
]);
assert.equal(event.numberOfListeners, 0);
});
test('engine event passes every argument and rejects non-functions', () => {
const event = createEngineEvent();
let args;
event.addEventListener((...values) => (args = values));
event.raiseEvent(1, 'two', null);
assert.deepEqual(args, [1, 'two', null]);
assert.throws(() => event.addEventListener(null), TypeError);
});
test('a listener removed during dispatch is not called in that dispatch', () => {
const event = createEngineEvent();
const seen = [];
let removeLater;
const removeSelf = event.addEventListener(() => {
seen.push('self');
removeSelf();
});
event.addEventListener(() => {
seen.push('remover');
removeLater();
});
removeLater = event.addEventListener(() => seen.push('later'));
event.addEventListener(() => seen.push('last'));
event.raiseEvent();
event.raiseEvent();
assert.deepEqual(seen, ['self', 'remover', 'last', 'remover', 'last']);
assert.equal(event.numberOfListeners, 2);
});
test('listeners added during dispatch run from the next raise', () => {
const event = createEngineEvent();
const seen = [];
event.addEventListener(() => {
seen.push('first');
if (seen.length === 1) event.addEventListener(() => seen.push('added'));
});
event.raiseEvent();
event.raiseEvent();
assert.deepEqual(seen, ['first', 'first', 'added']);
});
test('adding the same listener twice registers it once; every remover handle is idempotent', () => {
const event = createEngineEvent();
let count = 0;
const listener = () => count++;
const first = event.addEventListener(listener);
const second = event.addEventListener(listener);
assert.equal(event.numberOfListeners, 1);
event.raiseEvent();
assert.equal(count, 1);
second();
second();
first();
event.raiseEvent();
assert.equal(count, 1);
assert.equal(event.numberOfListeners, 0);
const again = event.addEventListener(listener);
first();
event.raiseEvent();
assert.equal(count, 2, 'a stale handle removed a newer registration');
again();
assert.equal(event.numberOfListeners, 0);
});
test('removing and re-adding a listener during dispatch leaves it registered', () => {
const event = createEngineEvent();
const seen = [];
const later = () => seen.push('later');
event.addEventListener(() => {
seen.push('first');
if (seen.length > 1) return;
event.removeEventListener(later);
event.addEventListener(later);
});
event.addEventListener(later);
event.raiseEvent();
assert.equal(event.numberOfListeners, 2);
event.raiseEvent();
assert.deepEqual(seen, ['first', 'first', 'later']);
});
test('engine events are branded so a raw Cesium.Event fails the shape check', () => {
assert.equal(isEngineEvent(createEngineEvent()), true);
const raw = { addEventListener() {}, removeEventListener() {} };
assert.equal(isEngineEvent(raw), false);
const engine = createFakeEngine();
assert.throws(
() =>
assertGlobeEngine({
...engine,
frames: { ...engine.frames, preRender: raw },
}),
/frames\.preRender/,
);
assert.deepEqual(MODIFIERS, ['ctrl', 'shift', 'alt']);
});
test('a throwing listener does not leave the event stuck in dispatch', () => {
const event = createEngineEvent();
const remove = event.addEventListener(() => {
throw new Error('boom');
});
assert.throws(() => event.raiseEvent(), /boom/);
remove();
assert.equal(event.numberOfListeners, 0);
let called = false;
event.addEventListener(() => (called = true));
event.raiseEvent();
assert.equal(called, true);
});
test('assertGlobeEngine accepts a complete engine and names every missing capability', () => {
const engine = createFakeEngine();
assert.equal(assertGlobeEngine(engine), engine);
assert.deepEqual(ENGINE_KINDS, ['cesium', 'navara']);
assert.deepEqual(INPUT_TYPES, ['click', 'doubleClick', 'move', 'down', 'up']);
const broken = {
...engine,
kind: 'webgl',
camera: { ...engine.camera, flyTo: undefined, moveEnd: {} },
frames: undefined,
surface: { ...engine.surface, supported: 'yes' },
};
delete broken.maps;
assert.throws(
() => assertGlobeEngine(broken),
(error) => {
assert.ok(error instanceof TypeError);
for (const path of [
'kind',
'camera.flyTo',
'camera.moveEnd',
'frames',
'surface.supported',
'maps',
])
assert.match(
error.message,
new RegExp(`\\b${path.replace('.', '\\.')}\\b`),
);
assert.doesNotMatch(error.message, /camera\.setView/);
return true;
},
);
assert.throws(() => assertGlobeEngine(null), TypeError);
});
test('the contract carries what the shell infrastructure needs', () => {
for (const member of [
'camera.livePosition',
'camera.height',
'maps.releasePhotorealTiles',
'maps.current',
])
assert.ok(GLOBE_ENGINE_MEMBERS.includes(member), member);
const engine = createFakeEngine();
const broken = {
...engine,
camera: { ...engine.camera, livePosition: undefined, height: 1 },
maps: { ...engine.maps, releasePhotorealTiles: undefined },
};
assert.throws(
() => assertGlobeEngine(broken),
/camera\.livePosition.*camera\.height.*maps\.releasePhotorealTiles/,
);
});
test('the contract carries what shell navigation needs', () => {
for (const member of ['camera.commanded', 'picker.pickGlobe', 'isDestroyed'])
assert.ok(GLOBE_ENGINE_MEMBERS.includes(member), member);
const engine = createFakeEngine();
const broken = {
...engine,
camera: { ...engine.camera, commanded: {} },
picker: { ...engine.picker, pickGlobe: undefined },
isDestroyed: false,
};
assert.throws(
() => assertGlobeEngine(broken),
/camera\.commanded.*picker\.pickGlobe.*isDestroyed/,
);
});
test('the fake engine passes the engine contract suite', async (t) => {
const engine = createFakeEngine();
const checks = createContractSuite(engine, {
waitFrames: async (count) => engine.fake.frames(count),
// The fake's input, as a real pointer would drive it.
pointer: {
click: async (x, y) => engine.fake.input('click', { position: { x, y } }),
move: async (x, y) =>
engine.fake.input('move', {
startPosition: { x: x - 1, y },
endPosition: { x, y },
}),
},
mapSources: {
imagery: [{ kind: 'osm' }, { kind: 'esri-imagery' }],
photoreal: { kind: 'photoreal' },
},
});
assert.ok(checks.length >= 15);
assert.ok(checks.some(({ name }) => name.startsWith('maps:')));
assert.equal(new Set(checks.map((check) => check.name)).size, checks.length);
for (const check of checks) await t.test(check.name, () => check.run());
});
test('the contract suite reports failures of a misbehaving engine', async () => {
const engine = createFakeEngine();
// An engine whose projection ignores the camera must fail the projector checks.
engine.fake.script('worldToWindow', () => ({ x: 0, y: 0 }));
const results = await runContractSuite(engine, {
waitFrames: async (count) => engine.fake.frames(count),
});
const failed = results.filter((result) => !result.ok);
assert.ok(failed.some((result) => /worldToWindow/.test(result.name)));
assert.ok(failed.every((result) => result.error instanceof Error));
assert.ok(results.some((result) => result.ok));
});
test('the contract suite rejects a raw Cesium-style event that double-registers', async () => {
const engine = createFakeEngine();
// Cesium.Event pushes a listener again when it is added twice.
const listeners = [];
const raw = {
addEventListener(listener) {
listeners.push(listener);
return () => raw.removeEventListener(listener);
},
removeEventListener(listener) {
const index = listeners.indexOf(listener);
if (index >= 0) listeners.splice(index, 1);
return index >= 0;
},
};
engine.frames.postRender.addEventListener((time) => {
for (const listener of [...listeners]) listener(time);
});
const wrapped = { ...engine, frames: { ...engine.frames, postRender: raw } };
const results = await runContractSuite(wrapped, {
waitFrames: async (count) => engine.fake.frames(count),
});
const failed = results.filter((result) => !result.ok).map((r) => r.name);
assert.ok(
failed.some((name) => /twice/.test(name)),
failed.join('\n'),
);
});
test('raiseValue raises exactly one argument with the event semantics', () => {
const event = createEngineEvent();
const seen = [];
const second = (...values) => seen.push(['second', values]);
event.addEventListener((...values) => {
seen.push(['first', values]);
event.removeEventListener(second);
});
event.addEventListener(second);
event.raiseValue(42);
assert.deepEqual(seen, [['first', [42]]]);
assert.equal(event.numberOfListeners, 1);
});
test('the contract carries the sharpening and checks its values', () => {
for (const member of ['render.setSharpen', 'render.sharpen'])
assert.ok(GLOBE_ENGINE_MEMBERS.includes(member), member);
assert.deepEqual(SHARPEN_INITIAL, { enabled: false, amount: 1 });
const on = mergeSharpen(SHARPEN_INITIAL, { enabled: true });
assert.deepEqual(on, { enabled: true, amount: 1 });
assert.deepEqual(mergeSharpen(on, { amount: 0 }), {
enabled: true,
amount: 0,
});
assert.deepEqual(mergeSharpen(on), on);
for (const bad of [
{ enabled: 1 },
{ amount: -1 },
{ amount: Infinity },
{ amount: null },
])
assert.throws(() => mergeSharpen(on, bad), TypeError);
});
test('the contract carries the app clock', () => {
for (const member of ['clock.now', 'clock.frameTime', 'clock.ticked'])
assert.ok(GLOBE_ENGINE_MEMBERS.includes(member), member);
const engine = createFakeEngine();
assert.equal(assertGlobeEngine(engine), engine);
const broken = {
...engine,
clock: { ...engine.clock, frameTime: 1, ticked: {} },
};
assert.throws(
() => assertGlobeEngine(broken),
/clock\.frameTime.*clock\.ticked/,
);
const missing = { ...engine };
delete missing.clock;
assert.throws(() => assertGlobeEngine(missing), /\bclock\b/);
});
test('the contract carries instanced movers', () => {
for (const member of ['movers.createSet', 'movers.list'])
assert.ok(GLOBE_ENGINE_MEMBERS.includes(member), member);
const engine = createFakeEngine();
const broken = { ...engine, movers: { createSet: 1 } };
assert.throws(
() => assertGlobeEngine(broken),
/movers\.createSet.*movers\.list/,
);
});
test('the contract carries dynamic lines', () => {
for (const member of ['lines.createLine', 'lines.list'])
assert.ok(GLOBE_ENGINE_MEMBERS.includes(member), member);
const engine = createFakeEngine();
assert.equal(assertGlobeEngine(engine), engine);
const broken = { ...engine, lines: {} };
assert.throws(
() => assertGlobeEngine(broken),
/lines\.createLine.*lines\.list/,
);
});