suaveplan/openspec/archive/2026-05-12-enterprise-network-testing/tasks.md

Tasks: enterprise-network-testing

Change ID: enterprise-network-testing Package: @suaveplan/network-testing Target path: universal/network/network-testing Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/testing

---

1. Scaffold

• Create universal/network/network-testing/ with src/, tests/, and all feature subdirectories.
• Write package.json at version 0.1.0: "sideEffects": false, exports map, deps per proposal.md.
• Write tsconfig.json, vitest.config.ts, scripts.

---

2. Types and error codes

• Define all public types in src/types/common.ts: MemoryTransport, MemoryTransportPair, MemoryTransportOptions, FakeWebSocketAdapter, FakeWebSocketHandle, FakeWebSocketOptions, NetworkConditions, LatencyDistribution, ConditionSimulator, SimulationStats, TestPeer, TestPeerOptions, NetworkEventCapture.
• Write src/types/common.md (≥200 words, simple + advanced examples).
• Define error codes in src/error-codes.ts.
• Write Zod schemas in src/types/schemas.ts + src/types/schemas.md.

---

3. Memory transport (src/transports/memory-transport/)

• Implement createMemoryTransport(options?) — returns MemoryTransportPair:
  • Two ends share a queue; client.send(m) pushes to server.messages, calls server's onmessage.
  • connect() sets both ends to connected.
  • disconnect() sets both ends to disconnected, fires ondisconnect.
  • Injectable Clock for latencyMs simulation (use setTimeout equivalent on clock).
• Write memory-transport.test.ts (≤500 lines): send client→server, server→client, disconnect, latency.
• Write memory-transport.md (≥200 words).

---

4. Fake WebSocket adapter (src/transports/fake-websocket/)

• Implement createFakeWebSocketAdapter(options?):
  • connect(url, protocols?) — creates a FakeWebSocketHandle, stores in connections.
  • simulateMessage(data) — calls onmessage on all handles.
  • simulateError(error) — calls onerror on all handles.
  • simulateClose(code?, reason?) — calls onclose on all handles.
  • FakeWebSocketHandle.send(data) — pushes to sentMessages.
  • autoConnect: true (default) calls onopen immediately after connect.
• Write fake-websocket.test.ts (≤500 lines): connect, send tracked, simulateMessage received, close, error.
• Write fake-websocket.md (≥200 words).

---

5. Condition simulator (src/simulators/condition-simulator/)

• Implement createConditionSimulator(conditions):
  • wrap(transport) — returns a proxy that intercepts send():
    • Roll packet drop: if rng.next() < conditions.packetLossRate, drop (return without sending).
    • Compute latency: sample from conditions.latencyMs distribution using injectable Rng.
    • Add jitter: ± conditions.jitterMs random offset.
    • After delay, call real transport.send().
  • setConditions(partial) — update conditions on the fly.
  • reset() — restore original conditions, clear stats.
  • Track sentMessages, droppedMessages, totalLatencyMs.
• Write condition-simulator.test.ts (≤500 lines): packet drop rate, latency added, stats tracked.
• Write condition-simulator.md (≥200 words).

---

6. Test peer factory (src/factories/test-peer/)

• Implement createTestPeer(options?):
  • Auto-generates id (test-peer-${n}) and address (127.0.0.1:${port}).
  • Fluent builder: withCapabilities, withRegion, withHealth.
  • asRegistryEntry() — returns RegistryEntry compatible shape.
  • asBootstrapSeed() — returns SeedConfig compatible shape.
• Write test-peer.test.ts + test-peer.md.

---

7. Network event capture (src/assertions/event-capture/)

• Implement createNetworkEventCapture(eventBus):
  • Subscribes to all events on the bus; pushes to events array.
  • waitFor(event, timeout?) — returns a Promise that resolves when the event fires; rejects after timeout.
  • assertEventEmitted(event, predicate?) — throws NetworkTestingError(NET_TEST_EVENT_NOT_EMITTED) if not found.
  • assertEventCount(event, count) — throws if actual count !== expected.
  • clear() — empties events.
• Write event-capture.test.ts + event-capture.md.

---

8. Integration test (tests/integration.test.ts)

• Create a MemoryTransportPair, send messages, verify receipt.
• Wrap a transport with ConditionSimulator (50% packet loss), send 100 messages, verify ~50 dropped.
• Use FakeWebSocketAdapter with a hypothetical client, simulate messages, verify received.

---

9. Docs and verify

• All per-file .md files per layout in proposal.md.
• universal/network/network-testing/README.md.
• bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-testing — all green, 100%.
• bun scripts/publish.ts --package @suaveplan/network-testing.
• Update CLAUDE.md. Archive change folder.