Files
gods-eye-view/src/layers/vessels/testing.js
T
Sameh Khamis 0a0c6a0e5b Vessel playback moves icons on the renderer's clock
While the timeline plays or is scrubbed, each vessel icon is handed to the
renderer as a motion segment along its track (a straight piece of at most
10 km between two fixes, on the scene clock), as aircraft already are. The
layer writes an icon again only when its segment runs out or the time
moves back before it, instead of moving every icon on the CPU every frame.

Behaviour is kept:
- Icons follow the same great-circle track between fixes (a 10 km chord
  stays within 2 m of it) with the same course.
- A vessel still appears TIMELINE_UNSEEN_MS before its first fix and
  hides again when the time moves back before that.
- Cards, the selected vessel, ship models and the vessel the bridge camera
  rides are read where they are every frame; the rest within
  HIDDEN_FOLLOW_MS, as before.
- Position reads (getAllPositions, getNearby, the focus pass, the
  detection overlay, single-vessel lookups) return where the icon is drawn
  at the world time.
- Going live, each icon holds where its segment last drew it, unless a
  live update has drawn it since.
- Trails are unchanged: they are built from the feed's fixes, not from the
  per-frame position.
- Live mode and renderers without the motionSegments capability take the
  previous path unchanged.
2026-11-15 23:56:03 -08:00

261 lines
8.5 KiB
JavaScript

import { DEFAULT_AIS_RUNTIME } from './policy.js';
import { createVesselIconBook } from './iconBook.js';
export function createTesting({
vesselState,
services,
parts: components,
layer,
options,
}) {
const { state } = vesselState;
const aisLiveVesselsLayer = layer;
/**
* Bind the production interaction callbacks to a mockable viewer. Clicks
* come through the viewer's input dispatcher (src/input/testDoubles.mjs).
* Test-only seam; behavior is shared with installInteraction().
* @param {Object} viewer - Viewer-like object with scene.pick().
* @param {Object} keyTarget - EventTarget-like object with add/removeEventListener().
* @returns {void}
*/
function _bindVesselInteractionForTest(viewer, keyTarget) {
components.selection.bindVesselInteraction(viewer, keyTarget);
}
/**
* Prime the minimum live state needed by interaction/lifecycle wire tests.
* @param {Object} [options={}] - Test state values.
* @returns {void}
*/
function _setVesselStateForTest(options = {}) {
components.lifecycle.resetState();
const records = Array.isArray(options.records) ? options.records : [];
// A test record that names no id is keyed by its MMSI, as an AIS feed's
// own rows are (see normalizeVessel).
for (const record of [...records, options.selectedRecord])
if (record && typeof record === 'object' && record.id === undefined)
record.id = String(record.mmsi || '').trim();
state.viewer = options.viewer || null;
state.feed.enabled = options.enabled !== false;
state.feed.loaded = options.loaded === true;
state.feed.loading = options.loading === true;
state.feed.stale = options.stale === true;
state.feed.partial = options.partial === true;
state.feed.error = options.error || null;
state.feed.lastUpdate = options.lastUpdate ?? null;
state.records.all = records;
state.feed.count = records.length;
state.records.byId = new Map(
records
.filter((record) => record?.id)
.map((record) => [record.id, record]),
);
state.selectedRecord = options.selectedRecord || null;
// `icons: null` leaves the layer to make its own draw set.
state.icons =
options.icons === null ? null : options.icons || createVesselIconBook();
state.trail = options.trail || null;
state.trailId = options.trailId || null;
state.trailPositions = Array.isArray(options.trailPositions)
? [...options.trailPositions]
: [];
state.feed.transportStatus = options.transportStatus || null;
state.feed.lastMessageAt = options.lastMessageAt ?? null;
state.feed.rawRowCount = Number.isFinite(options.rawRowCount)
? options.rawRowCount
: 0;
state.feed.acceptedRowCount = Number.isFinite(options.acceptedRowCount)
? options.acceptedRowCount
: records.length;
state.feed.firstConnectPhase = options.firstConnectPhase || 'idle';
state.feed.firstConnectStartedAt = options.firstConnectStartedAt ?? null;
state.feed.firstConnectDeadline = options.firstConnectDeadline ?? null;
state.interactionKeyTarget = options.interactionKeyTarget || null;
}
/** Inject a host recorder for lifecycle/contract tests; null restores production. */
function _setVesselOverlayHostForTest(host = null) {
vesselState._vesselOverlayHost =
host || vesselState.DEFAULT_VESSEL_OVERLAY_HOST;
}
/** Exercise the production selector/publisher through a test-owned state. */
function _updateVesselCardsForTest(records = []) {
components.rendering.updateClusteredLabels(records);
}
/**
* Reconcile AIS rows through the production lifecycle. Test-only seam.
* @param {Object} viewer - Viewer-like object.
* @param {Array<Object>} rows - Raw AIS rows.
* @returns {void}
*/
function _reconcileVesselsForTest(viewer, rows) {
components.snapshots.reconcileVessels(viewer, rows);
}
/** Apply one server snapshot through the production pre-reconcile health gate. */
function _applyAisFeedSnapshotForTest(viewer, payload) {
return components.ingestion.applyAisFeedSnapshot(viewer, payload);
}
/** Exercise the request-owned live loader with a test-controlled fetch. */
function _loadLivePositionsForTest(viewer) {
return components.ingestion.loadLivePositions(viewer);
}
/** Start the production first-connect grace state without installing UI. */
function _beginAisSessionForTest() {
components.lifecycle.beginAisSession();
}
/** Inject a deterministic clock/scheduler; null restores production runtime. */
function _setAisRuntimeForTest(runtime = null) {
components.lifecycle.clearFirstConnectTimer();
vesselState._aisRuntime = runtime
? {
now: runtime.now,
setTimeout: runtime.setTimeout,
clearTimeout: runtime.clearTimeout,
}
: DEFAULT_AIS_RUNTIME;
}
/** Read feed-health fields without exposing mutable production state. */
function _getVesselFeedStateForTest() {
const stats = aisLiveVesselsLayer.getStats();
return {
count: state.feed.count,
loaded: state.feed.loaded,
loading: stats.loading,
loadingLabel: stats.loadingLabel,
stale: state.feed.stale,
error: state.feed.error,
status: stats.status,
lastUpdate: state.feed.lastUpdate,
transportStatus: state.feed.transportStatus,
lastMessageAt: state.feed.lastMessageAt,
rawRowCount: state.feed.rawRowCount,
acceptedRowCount: state.feed.acceptedRowCount,
selectedId: state.selectedRecord?.id || null,
trailId: state.trailId,
trailPositionCount: state.trailPositions.length,
sessionId: state.feed.sessionId,
firstConnectPhase: state.feed.firstConnectPhase,
firstConnectStartedAt: state.feed.firstConnectStartedAt,
firstConnectDeadline: state.feed.firstConnectDeadline,
};
}
/** Run one preRender visibility/focus pass. Test-only seam. */
function _runVisibilityPassForTest(force = false) {
components.rendering.updateVisibility(force);
}
/** Draw a record's visual where it stands now. Test-only seam. */
function _prepareVesselVisualForTest(record) {
return components.rendering.prepareRecordVisual(record);
}
/** A record's visual (the record itself before it has one). Test-only seam. */
function _vesselVisualForTest(record) {
return components.rendering.getVisual(record);
}
/** Run one live placement pass (a host-supplied placement). Test-only seam. */
function _runPlacementPassForTest() {
components.rendering.followPlacements();
}
/**
* Run what one live frame runs (not following the clock): settle whether
* icons move on the renderer's clock, then the placement pass. Test-only
* seam.
*/
function _runLiveFrameForTest() {
components.rendering.syncSegments();
components.rendering.followPlacements();
}
/** Run one world-clock pass at world time `atMs`. Test-only seam. */
function _runClockPassForTest(atMs) {
vesselState.worldNow = () => atMs;
components.rendering.followClock();
}
/**
* Follow the world clock, standing at world time `atMs`; `null` goes back
* to live. Test-only seam.
*/
function _followClockForTest(atMs) {
vesselState.timeline = { active: () => atMs !== null };
vesselState.worldNow = () => atMs ?? 0;
}
/** True while a trailing visibility frame is scheduled. Test-only seam. */
function _hasTrailingVisibilityPassForTest() {
return state.trailingVisibilityTimer !== null;
}
/**
* Read lifecycle ownership state without exposing the mutable state object.
* Test-only seam.
* @returns {{trailId: string|null, trailPositionCount: number, vesselCount: number}}
*/
function _getVesselStateForTest() {
return {
trailId: state.trailId,
trailPositionCount: state.trailPositions.length,
vesselCount: state.records.byId.size,
};
}
/** The layer's record for a vessel id, or null. Test-only seam. */
function _vesselRecordForTest(id) {
return state.records.byId.get(id) ?? null;
}
return {
_bindVesselInteractionForTest,
_setVesselStateForTest,
_followClockForTest,
_setVesselOverlayHostForTest,
_updateVesselCardsForTest,
_reconcileVesselsForTest,
_applyAisFeedSnapshotForTest,
_loadLivePositionsForTest,
_beginAisSessionForTest,
_setAisRuntimeForTest,
_getVesselFeedStateForTest,
_getVesselStateForTest,
_vesselRecordForTest,
_runVisibilityPassForTest,
_prepareVesselVisualForTest,
_vesselVisualForTest,
_runPlacementPassForTest,
_runClockPassForTest,
_runLiveFrameForTest,
_hasTrailingVisibilityPassForTest,
};
}