Compare commits

..
Author SHA1 Message Date
Antigravity AI 922b7acc03 test(incidents): guard tests for BaseIncidentPlugin WebSocket payload contract
12 tests across 4 describe blocks document the WsClient payload contract:
- 2 it.fails tests assert the DESIRED post-fix unwrap behaviour for the canonical
  scheduler envelope { source, fetchedAt, items, totalCount } and GeoJSON
  FeatureCollection { features: [...] } shapes — currently fail because
  BaseIncidentPlugin has no mapWebsocketPayload.
- 2 companion 'currently drops' tests explicitly document the live silent-drop
  behaviour so anyone reading the file understands the failure mode.
- 4 working-behaviour tests assert flat GeoEntity[] passthrough, timestamp
  normalisation, and subclass override precedence — must stay green.
- 4 structural-contract tests document missing mapWebsocketPayload, required
  lifecycle methods, polling interval, and layer config defaults.

The it.fails tests will flip to passing in the follow-up fix PR, at which point
the 2 'currently drops' companions are deleted and the 'does NOT have
mapWebsocketPayload' assertion is updated.
2026-05-24 13:33:33 +12:00
Silvertakana dc83f97be4 feat(auth): ADR-001 Workstream C — ticket auth, SSRF, and WebSocket first-message auth (#180)
* docs: add ADR-003 document and update cloud-auth-architecture superseded notice

* chore: bump version for ADR-001 Workstream C

* fix: remove stray 'r' prefix on import in places/details route

rimport typo on line 1 of src/app/api/places/details/route.ts caused
TS1435 (unknown keyword), ESLint parse error, and a webpack build failure
in Docker CI. Corrected to a valid import statement.
2026-05-23 16:16:31 +12:00
2 changed files with 355 additions and 1 deletions

No files matched your search

+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@worldwideview/wwv-lib-incidents",
"version": "1.0.2",
"version": "1.0.3",
"description": "Shared abstract base classes for WorldWideView incident plugins (earthquakes, wildfires, conflicts)",
"main": "src/index.ts",
"types": "src/index.ts",
@@ -0,0 +1,354 @@
/**
* Guard tests for the BaseIncidentPlugin WebSocket payload contract.
*
* CONTEXT — The bug being guarded against:
* WsClient.handleDataMessage (src/core/data/WsClient.ts, lines 166-190) has three branches:
* 1. Plugin has `mapWebsocketPayload` → called with raw payload → must return GeoEntity[]
* 2. No handler AND payload IS a flat array → used directly (timestamps normalised)
* 3. No handler AND payload is ANY OTHER object → silently dropped (console.warn + return)
*
* BaseIncidentPlugin currently has NO `mapWebsocketPayload`. The canonical data-engine
* scheduler wraps snapshots as `{ source, fetchedAt, items, totalCount }` (an object, not
* an array), so branch 3 fires for every BaseIncidentPlugin subclass whose seeder uses the
* standard scheduler wrapper — including the earthquakes plugin.
*
* TEST STRATEGY:
* - it.fails(...) → asserts the DESIRED post-fix behavior; currently fails → proves the bug.
* CI will flip these to green once BaseIncidentPlugin gains mapWebsocketPayload.
* - it(...) → asserts current working behaviour that must NOT regress.
*/
import { describe, it, expect } from "vitest";
import { BaseIncidentPlugin } from "./index";
import type {
GeoEntity,
TimeRange,
ServerPluginConfig,
FilterDefinition,
PluginCategory,
CesiumEntityOptions,
} from "@worldwideview/wwv-plugin-sdk";
// ─── Minimal GeoEntity factory ────────────────────────────────────────────────
function makeEntity(id: string, overrides: Partial<GeoEntity> = {}): GeoEntity {
return {
id,
pluginId: "test-incident-plugin",
latitude: 35.6762,
longitude: 139.6503,
timestamp: new Date("2025-01-01T00:00:00Z"),
properties: {},
...overrides,
};
}
// ─── Minimal concrete subclass ────────────────────────────────────────────────
// We keep it as bare-bones as possible — only the abstract members required to
// instantiate the class. We do NOT add mapWebsocketPayload here, so we're testing
// the BaseIncidentPlugin base behaviour exactly.
class MinimalIncidentPlugin extends BaseIncidentPlugin {
id = "test-incident-plugin";
name = "Test Incident Plugin";
description = "Test";
icon = null;
category: PluginCategory = "natural-disaster";
version = "0.0.1";
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
return [];
}
getServerConfig(): ServerPluginConfig {
return {
apiBasePath: "/api/test-incident-plugin",
streamUrl: "ws://localhost:5001/stream",
pollingIntervalMs: 0,
};
}
getFilterDefinitions(): FilterDefinition[] {
return [];
}
getLegend(): { label: string; color: string; filterId?: string; filterValue?: string }[] {
return [];
}
protected getSeverityValue(_entity: GeoEntity): number {
return 0;
}
protected getSeverityColor(_value: number): string {
return "#ef4444";
}
protected getSeveritySize(_value: number): number {
return 10;
}
}
// ─── Subclass that DOES override mapWebsocketPayload ─────────────────────────
const FIXED_ENTITIES = [makeEntity("override-1"), makeEntity("override-2")];
class OverridingIncidentPlugin extends MinimalIncidentPlugin {
id = "overriding-incident-plugin";
mapWebsocketPayload(_payload: unknown, _existingEntities?: GeoEntity[]): GeoEntity[] {
return FIXED_ENTITIES;
}
}
// ─── Helpers that mimic WsClient.handleDataMessage branching logic ────────────
// We test the plugin method in isolation (unit test), not the full WsClient,
// because WsClient has DOM/Zustand/DataBus dependencies. This mirrors the exact
// logic from WsClient lines 172-182.
function simulateWsClientDispatch(
plugin: BaseIncidentPlugin,
rawPayload: unknown
): GeoEntity[] | null {
if (typeof (plugin as any).mapWebsocketPayload === "function") {
return (plugin as any).mapWebsocketPayload(rawPayload, []);
}
if (!Array.isArray(rawPayload)) {
// This is the silent-drop branch — return null to signal "dropped"
return null;
}
return (rawPayload as GeoEntity[]).map((e) => ({
...e,
timestamp: new Date(e.timestamp || Date.now()),
}));
}
// ─── Test suite ───────────────────────────────────────────────────────────────
describe("BaseIncidentPlugin — WebSocket payload contract", () => {
describe("scheduler-wrapped payload { source, fetchedAt, items, totalCount }", () => {
/**
* DESIRED behavior: BaseIncidentPlugin.mapWebsocketPayload should unwrap the
* canonical scheduler envelope and return the items array as GeoEntity[].
*
* CURRENT state: the method does not exist on BaseIncidentPlugin, so
* simulateWsClientDispatch returns null (silent drop) instead of the items.
*
* This test is marked it.fails so CI proves the bug today and will automatically
* turn green once the fix is landed.
*/
it.fails(
"unwraps { source, fetchedAt, items, totalCount } and returns items as GeoEntity[] " +
"(CURRENTLY FAILS — BaseIncidentPlugin has no mapWebsocketPayload)",
() => {
const plugin = new MinimalIncidentPlugin();
const entity1 = makeEntity("eq-1");
const entity2 = makeEntity("eq-2");
const wrappedPayload = {
source: "usgs-earthquake-feed",
fetchedAt: "2025-01-01T00:00:00Z",
items: [entity1, entity2],
totalCount: 2,
};
// After the fix: mapWebsocketPayload should exist and return both entities
const result = simulateWsClientDispatch(plugin, wrappedPayload);
expect(result).not.toBeNull();
expect(Array.isArray(result)).toBe(true);
expect(result).toHaveLength(2);
expect(result![0].id).toBe("eq-1");
expect(result![1].id).toBe("eq-2");
}
);
/**
* Documents the CURRENT broken behaviour explicitly.
* When the fix lands, this test should be DELETED (the positive assertion above replaces it).
*/
it(
"currently drops the wrapped payload silently (returns null) because mapWebsocketPayload is absent",
() => {
const plugin = new MinimalIncidentPlugin();
const wrappedPayload = {
source: "usgs-earthquake-feed",
fetchedAt: "2025-01-01T00:00:00Z",
items: [makeEntity("eq-1")],
totalCount: 1,
};
// simulateWsClientDispatch returns null to represent the silent drop
const result = simulateWsClientDispatch(plugin, wrappedPayload);
expect(result).toBeNull();
}
);
});
describe("flat GeoEntity[] payload", () => {
/**
* Flat arrays bypass mapWebsocketPayload entirely in WsClient — they work today.
* This test MUST stay green before and after the fix.
*/
it("passes flat GeoEntity[] through unchanged (current working behaviour)", () => {
const plugin = new MinimalIncidentPlugin();
const entities = [makeEntity("eq-flat-1"), makeEntity("eq-flat-2")];
const result = simulateWsClientDispatch(plugin, entities);
expect(result).not.toBeNull();
expect(result).toHaveLength(2);
expect(result![0].id).toBe("eq-flat-1");
expect(result![1].id).toBe("eq-flat-2");
});
it("normalises timestamp strings to Date objects for flat array payloads", () => {
const plugin = new MinimalIncidentPlugin();
const raw = [{
...makeEntity("eq-ts-1"),
// Simulate a timestamp that arrives over the wire as a string
timestamp: "2025-06-01T12:00:00Z" as unknown as Date,
}];
const result = simulateWsClientDispatch(plugin, raw);
expect(result).not.toBeNull();
expect(result![0].timestamp).toBeInstanceOf(Date);
});
});
describe("GeoJSON { features: [...] } payload", () => {
/**
* DESIRED behavior: BaseIncidentPlugin.mapWebsocketPayload should normalise a
* GeoJSON FeatureCollection envelope into a GeoEntity[].
*
* CURRENT state: no mapWebsocketPayload → silent drop (null).
*
* Marked it.fails for the same reason as the scheduler-wrapped test.
*/
it.fails(
"normalises a GeoJSON FeatureCollection into GeoEntity[] " +
"(CURRENTLY FAILS — BaseIncidentPlugin has no mapWebsocketPayload)",
() => {
const plugin = new MinimalIncidentPlugin();
const geojsonPayload = {
type: "FeatureCollection",
features: [
{
type: "Feature",
geometry: { type: "Point", coordinates: [139.65, 35.68] },
properties: { id: "gj-1", magnitude: 4.5 },
},
{
type: "Feature",
geometry: { type: "Point", coordinates: [135.50, 34.69] },
properties: { id: "gj-2", magnitude: 3.1 },
},
],
};
const result = simulateWsClientDispatch(plugin, geojsonPayload);
expect(result).not.toBeNull();
expect(Array.isArray(result)).toBe(true);
expect(result).toHaveLength(2);
// Each feature should have been converted to a GeoEntity with lat/lon
expect(result![0].latitude).toBeCloseTo(35.68, 2);
expect(result![0].longitude).toBeCloseTo(139.65, 2);
}
);
it(
"currently drops a GeoJSON FeatureCollection silently because mapWebsocketPayload is absent",
() => {
const plugin = new MinimalIncidentPlugin();
const geojsonPayload = {
type: "FeatureCollection",
features: [
{
type: "Feature",
geometry: { type: "Point", coordinates: [139.65, 35.68] },
properties: {},
},
],
};
const result = simulateWsClientDispatch(plugin, geojsonPayload);
expect(result).toBeNull();
}
);
});
describe("subclass override of mapWebsocketPayload", () => {
/**
* A subclass that implements mapWebsocketPayload is handled correctly TODAY.
* This covers the "conflict-events" / "iranwarlive" pattern and must stay green.
*/
it("calls the subclass override and returns its result regardless of payload shape", () => {
const plugin = new OverridingIncidentPlugin();
// Even if the payload is an object (which would normally be dropped), the
// subclass override is respected.
const wrappedPayload = {
source: "conflict-api",
fetchedAt: "2025-01-01T00:00:00Z",
items: [makeEntity("conflict-1")],
totalCount: 1,
};
const result = simulateWsClientDispatch(plugin, wrappedPayload);
// Should return the overriding subclass's fixed result, not the raw items
expect(result).toStrictEqual(FIXED_ENTITIES);
});
it("override is also called for flat array payloads, taking precedence over default handling", () => {
const plugin = new OverridingIncidentPlugin();
const flatPayload = [makeEntity("flat-1"), makeEntity("flat-2"), makeEntity("flat-3")];
const result = simulateWsClientDispatch(plugin, flatPayload);
// The override always wins — result is FIXED_ENTITIES, not the 3-element flat array
expect(result).toStrictEqual(FIXED_ENTITIES);
expect(result).toHaveLength(2);
});
});
describe("BaseIncidentPlugin structural contract", () => {
/**
* Confirm mapWebsocketPayload is NOT present on BaseIncidentPlugin today.
* This is the definitive proof of the bug — once the fix is added, this test
* should be updated (or removed) alongside the it.fails tests above.
*/
it("does NOT have mapWebsocketPayload defined (confirms the bug exists)", () => {
const plugin = new MinimalIncidentPlugin();
expect(typeof (plugin as any).mapWebsocketPayload).toBe("undefined");
});
it("implements the required WorldPlugin lifecycle methods", () => {
const plugin = new MinimalIncidentPlugin();
expect(typeof plugin.initialize).toBe("function");
expect(typeof plugin.destroy).toBe("function");
expect(typeof plugin.fetch).toBe("function");
expect(typeof plugin.getPollingInterval).toBe("function");
expect(typeof plugin.getLayerConfig).toBe("function");
expect(typeof plugin.renderEntity).toBe("function");
});
it("returns polling interval of 0 (WebSocket-only mode)", () => {
const plugin = new MinimalIncidentPlugin();
expect(plugin.getPollingInterval()).toBe(0);
});
it("returns default layer config with clustering enabled", () => {
const plugin = new MinimalIncidentPlugin();
const config = plugin.getLayerConfig();
expect(config.clusterEnabled).toBe(true);
expect(config.color).toBe("#ef4444");
expect(typeof config.clusterDistance).toBe("number");
});
});
});