suaveplan/openspec/changes/enterprise-testing-load-perf/specs/testing-load/spec.md

ADDED Requirements

Requirement: Package layout and dependency policy

The @suaveplan/testing-load package SHALL live at packages/testing/testing-load/. Its dependencies, peerDependencies, and devDependencies MUST NOT list any @suaveplan/* workspace package other than @suaveplan/types. External deps SHALL be referenced via catalog entries (no bare version strings). The package SHALL declare "sideEffects": false and SHALL provide a subpath export per feature module per openspec/AGENTS.md §6.

Scenario: Workspace deps are limited to @suaveplan/types

• WHEN bunx turbo ls --filter=@suaveplan/testing-load... is run
• THEN the only @suaveplan/* package in the forward closure MUST be @suaveplan/types

Scenario: No bare versions

• WHEN the package's package.json dependencies and devDependencies are scanned
• THEN every external dep MUST resolve to a catalog:<key> reference AND no bare semver string MUST appear

Requirement: Public API — defineLoadScenario, runLoadScenario, assertThresholds

The package SHALL export defineLoadScenario(spec) returning a frozen LoadScenario, runLoadScenario(scenario, opts?) returning Promise<{ summary: LoadSummary; raw: unknown }>, and assertThresholds(summary) returning void (throws on violation). Inputs SHALL be Zod-validated at the boundary; outputs SHALL conform to the LoadSummary shape regardless of which driver produced them. Every public function SHALL accept an optional { signal?: AbortSignal } and SHALL respect cancellation at bounded checkpoints.

Scenario: defineLoadScenario validates input

• WHEN defineLoadScenario({ name: "x", target: "not-a-url", vus: -1, duration: "30s" }) is called
• THEN it MUST throw TestingLoadError with code === "TESTING_LOAD.CONFIG_INVALID" AND context.issues MUST list the offending fields

Scenario: runLoadScenario honours AbortSignal

• WHEN runLoadScenario(scenario, { signal }) is awaited and signal.abort() is called mid-run
• THEN the promise MUST reject with TestingLoadError where code === "TESTING_LOAD.ABORTED" AND cause === signal.reason

Scenario: assertThresholds enumerates failed predicates

• WHEN a LoadSummary reports http_req_duration{p(95)} = 750 against threshold p(95)<500
• THEN assertThresholds(summary) MUST throw TestingLoadError with code === "TESTING_LOAD.THRESHOLD_VIOLATION" AND context.failed MUST list the predicate "http_req_duration: p(95)<500 (observed 750)"

Requirement: Driver pluggability — k6 primary, autocannon fallback

The package SHALL expose a LoadDriver interface and SHALL ship two implementations: a k6 driver invoking grafana/k6 via testcontainers, and an autocannon driver running in-process via the autocannon npm package. runLoadScenario SHALL default to the k6 driver when reachable and SHALL fall back to autocannon when k6 is unavailable. Both drivers SHALL normalise their output into the same LoadSummary shape so callers and assertThresholds are driver-agnostic.

Scenario: k6 selected when available

• WHEN runLoadScenario(scenario) is called without an explicit driver AND a reachable Docker daemon is detected AND the grafana/k6 image can be pulled
• THEN the k6 driver MUST be selected AND the resulting summary.driverName MUST equal "k6"

Scenario: autocannon fallback when k6 unavailable

• WHEN runLoadScenario(scenario) is called without an explicit driver AND no Docker daemon is reachable
• THEN the autocannon driver MUST be selected AND the resulting summary.driverName MUST equal "autocannon"

Scenario: Both drivers produce LoadSummary

• WHEN the same LoadScenario is executed once via the k6 driver and once via the autocannon driver
• THEN both runs MUST return a LoadSummary with the same set of metric keys (e.g. http_req_duration, http_req_failed, iteration_duration) AND assertThresholds MUST evaluate identically against either summary

Requirement: Default thresholds and per-scenario overrides

The package SHALL apply default thresholds when the caller omits the thresholds field on a LoadScenario: http_req_duration{p(95)} < 500ms, http_req_failed < 1% (rate < 0.01), iteration_duration{p(99)} < 2000ms. Caller-supplied thresholds SHALL merge on top of (not replace) the defaults; an explicit thresholds: {} SHALL retain the defaults; callers SHALL be able to override a single key without restating the rest.

Scenario: Defaults applied when omitted

• WHEN defineLoadScenario({ name: "x", target: "http://t/", vus: 1, duration: "30s" }) is called and the resulting scenario is inspected
• THEN the resolved thresholds MUST contain http_req_duration: ["p(95)<500"] AND http_req_failed: ["rate<0.01"] AND iteration_duration: ["p(99)<2000"]

Scenario: Single-key override merges with defaults

• WHEN defineLoadScenario({ ..., thresholds: { http_req_duration: ["p(95)<200"] } }) is called
• THEN the resolved scenario's http_req_duration MUST equal ["p(95)<200"] AND the other default keys MUST remain present unchanged

Requirement: Run-mode presets — smoke, load, stress, spike

The package SHALL export named run-mode presets composable with defineLoadScenario: smoke (1 vu, 30s), load (10 vu, 5m), stress (50 vu, 10m), spike (stages from 0 to 100 vu over 30s). Presets SHALL be plain objects spreadable into defineLoadScenario's spec argument; callers SHALL be able to override any preset field on a per-scenario basis.

Scenario: smoke preset values

• WHEN the smoke preset is inspected
• THEN vus === 1 AND duration === "30s" AND stages MUST be undefined

Scenario: spike preset values

• WHEN the spike preset is inspected
• THEN stages MUST describe a ramp from 0 to 100 virtual users over 30s AND the total scenario duration MUST equal the sum of stage durations

Requirement: Structured errors with TESTING_LOAD.* codes

The package SHALL throw only subclasses of TestingLoadError extends Error with stable codes prefixed TESTING_LOAD.*. Errors MUST carry { code, cause?, context? } fields. The package MUST NOT throw plain Error or TypeError from any public code path. Defined codes include TESTING_LOAD.CONFIG_INVALID, TESTING_LOAD.DRIVER_FAILED, TESTING_LOAD.DRIVER_UNAVAILABLE, TESTING_LOAD.THRESHOLD_VIOLATION, and TESTING_LOAD.ABORTED.

Scenario: Driver failure produces coded error

• WHEN the k6 driver's container exits non-zero
• THEN the driver MUST throw TestingLoadError with code === "TESTING_LOAD.DRIVER_FAILED" AND context.driverName === "k6" AND context.exitCode MUST equal the observed exit code

Scenario: Driver unavailable surfaces a typed error

• WHEN runLoadScenario is called with driver: "k6" explicitly AND no Docker daemon is reachable
• THEN the call MUST throw TestingLoadError with code === "TESTING_LOAD.DRIVER_UNAVAILABLE" AND context.driverName === "k6"

Requirement: 100% Istanbul coverage and self-testability

The package SHALL meet 100% Istanbul statement / branch / function / line coverage. The k6 driver SHALL accept injectable exec and fetch shims so the package's own test suite runs without a Docker daemon. The autocannon driver SHALL accept an injectable autocannon factory so the package's own test suite runs without performing real network requests.

Scenario: Coverage gate at 100%

• WHEN bunx turbo test:coverage --filter=@suaveplan/testing-load runs
• THEN statement, branch, function, and line coverage MUST each be 100%

Scenario: Tests pass without Docker

• WHEN the package's test suite is invoked on a host with no Docker daemon and no network access
• THEN every test MUST pass AND no test MUST attempt a real docker invocation or a real outbound network request