Initial Commit

openspec/changes/enterprise-testing-integration/specs/testing-integration-redis/spec.md

@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: Redis 7 image policy
+
+The `@suaveplan/testing-integration-redis` plugin SHALL pin to `redis:7` (name + major version). A follow-up operational change tracked at `docs/superpowers/specs/2026-04-25-test-suite-audit.md §5` will pin to `sha256:<digest>`.
+
+#### Scenario: Image tag pinned
+
+- **WHEN** the container factory is invoked without injection
+- **THEN** the resulting container uses image `redis:7`
+
+### Requirement: Env-bridge contract
+
+The plugin SHALL declare and forward the environment variable `REDIS_URL`. When `REDIS_URL` is set on the parent process at construction time, the fixture MUST enter env-bridge passthrough mode and parse the URL into host/port/password fields populated on `config`.
+
+#### Scenario: env() returns REDIS_URL
+
+- **WHEN** the fixture has started in container mode
+- **THEN** `fixture.env()` returns `{ REDIS_URL: "redis://…" }`
+
+#### Scenario: URL parsing in passthrough mode
+
+- **WHEN** `REDIS_URL=redis://:secret@redis.local:6380` is set at construction
+- **THEN** `config.host === "redis.local"` AND `config.port === 6380` AND `config.password === "secret"` AND container start is skipped
+
+### Requirement: Healthcheck contract
+
+`isHealthy()` SHALL open a TCP connection to the configured host/port, send the Redis `PING` command, and resolve `true` on receipt of `+PONG\r\n`. Connection errors, malformed replies, AND any non-PONG payload MUST resolve to `false`, never throw.
+
+#### Scenario: PING/PONG roundtrip
+
+- **WHEN** the Redis server replies `+PONG\r\n` to a PING
+- **THEN** `isHealthy()` resolves `true`
+
+#### Scenario: Connection refused
+
+- **WHEN** the port is closed
+- **THEN** `isHealthy()` resolves `false` and does not throw
+
+### Requirement: Injectable TCP ping
+
+The fixture constructor SHALL accept an optional `tcpPingFn` parameter. The default opens a real TCP socket; tests MAY replace it with a deterministic stub.
+
+#### Scenario: Injected ping drives health probe
+
+- **WHEN** `tcpPingFn` is replaced with `async () => false`
+- **THEN** `isHealthy()` resolves `false`
+
+### Requirement: Error-code prefix
+
+Errors thrown from the plugin SHALL carry codes matching `^INTEGRATION\.REDIS\.[A-Z_]+$` (e.g. `INTEGRATION.REDIS.START_FAILED`, `INTEGRATION.REDIS.STOP_FAILED`, `INTEGRATION.REDIS.URL_PARSE_FAILED`).
+
+#### Scenario: Malformed REDIS_URL is coded
+
+- **WHEN** `REDIS_URL` is set to a string that is not a valid URL
+- **THEN** the constructor throws with `code === "INTEGRATION.REDIS.URL_PARSE_FAILED"` AND `context.value` echoes the bad input