# Validation: natsClient_JS

The enforcer. Every specification rule (SP-XXX), walkthrough journey (WT-XXX), and NFR threshold
has a corresponding test. Tests are defined before implementation.

## Sources Under Test

| Source Document | What Validation Tests |
|-----------------|----------------------|
| **1. Requirements** | NFR-102 reconnect, NFR-201 store, NFR-302 per-message error guard, NFR-501 cleanup |
| **2. Solution Design** | SD-001 shared conn, SD-003 encode/decode, SD-004 status, SD-005 cleanup, SD-006 msghandler |
| **3. Walkthrough** | WT-001..WT-008 flows |
| **4. Specification** | SP-001..SP-008 signatures and behaviors |
| **5. Msghandler** | SP-010/SP-011 envelope round-trips |

## Specification-to-Test Execution Trace

| Requirement/Spec ID | Participant | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status |
|---------------------|-------------|-------------|----------------|-------------------|------------------------|---------|--------|
| SP-001 | — | `4-specification.md:SP-001` | `tests/unit/getNats.test.js` | `sets_connected_status` | — | `ci/contract-validation.yaml` | Pass |
| SP-002 | — | `4-specification.md:SP-002` | `tests/unit/subscribe.test.js` | `decodes_json_message` | — | `ci/contract-validation.yaml` | Pass |
| SP-002 | — | `4-specification.md:SP-002` | `tests/unit/subscribe.test.js` | `falls_back_to_text` | — | `ci/contract-validation.yaml` | Pass |
| SP-003 | — | `4-specification.md:SP-003` | `tests/unit/publish.test.js` | `stringifies_object_payload` | — | `ci/contract-validation.yaml` | Pass |
| SP-004 | — | `4-specification.md:SP-004` | `tests/unit/request.test.js` | `returns_decoded_reply` | — | `ci/contract-validation.yaml` | Pass |
| SP-005 | — | `4-specification.md:SP-005` | `tests/unit/reply.test.js` | `publishes_handler_response` | — | `ci/contract-validation.yaml` | Pass |
| SP-006 | — | `4-specification.md:SP-006` | `tests/unit/sendMsghandlerRequest.test.js` | `returns_dictionary_payload` | — | `ci/contract-validation.yaml` | Pass |
| SP-006 | — | `4-specification.md:SP-006` | `tests/unit/sendMsghandlerRequest.test.js` | `throws_on_text_payload` | — | `ci/contract-validation.yaml` | Pass |
| SP-007 | — | `4-specification.md:SP-007` | `tests/unit/closeNats.test.js` | `unsubscribes_all` | — | `ci/contract-validation.yaml` | Pass |
| SP-008 | — | `4-specification.md:SP-008` | `tests/unit/connectionStatus.test.js` | `emits_connecting_then_connected` | — | `ci/contract-validation.yaml` | Pass |
| WT-001 | Consuming App | `3-walkthrough.md:#session-start` | — | — | `tests/integration/connect.test.js` | `ci/integration.yaml` | Pass |
| WT-003 | Consuming App | `3-walkthrough.md:#wt-003` | — | — | `tests/integration/publish-flow.test.js` | `ci/integration.yaml` | Pass |
| WT-006 | Consuming App | `3-walkthrough.md:#wt-006` | — | — | `tests/integration/msghandler-flow.test.js` | `ci/integration.yaml` | Pass |
| WT-007 | Consuming App | `3-walkthrough.md:#wt-007` | — | — | `tests/integration/reconnect.test.js` | `ci/integration.yaml` | Pass |
| NFR-102 | — | `1-requirements.md:4.2` | — | — | `tests/integration/reconnect.test.js` | `ci/integration.yaml` | Pass |
| NFR-201 | — | `1-requirements.md:4.3` | — | — | `tests/integration/status-store.test.js` | `ci/integration.yaml` | Pass |
| NFR-302 | — | `1-requirements.md:4.4` | `tests/unit/subscribe.test.js` | `decode_error_does_not_crash` | — | `ci/integration.yaml` | Pass |
| NFR-501 | — | `1-requirements.md:4.5` | — | — | `tests/integration/close-flow.test.js` | `ci/integration.yaml` | Pass |
| SD-001 | — | `2-solution_design.md:5.1` | `tests/unit/getNats.test.js` | `returns_shared_connection` | — | `ci/integration.yaml` | Pass |
| SD-006 | — | `2-solution_design.md:5.1` | `tests/unit/sendMsghandlerRequest.test.js` | `delegates_to_smartpack` | — | `ci/integration.yaml` | Pass |

## Test Types

| Test Type | Source | Example Reference |
|-----------|--------|-------------------|
| Unit tests | `4-specification.md`, `natsClient.js` | `SP-002` falls back to `{ text }`; `SP-006` throws on `text` |
| Integration tests | `3-walkthrough.md`, `4-specification.md` | `WT-001` connect → `SP-001` |
| Performance tests | `1-requirements.md` NFRs | N/A for a client library (KPI-001 coverage) |

## Trace Rules

- Every specification item with a concrete behavior (SP-XXX) has at least one unit test — each spec
  item carries an `SP-XXX` ID.
- Every walkthrough journey (WT-XXX) has at least one integration test.
- Every NFR has at least one corresponding test (reconnect, store, error guard, cleanup).
- Every msghandler envelope case (SP-010/SP-011) is covered by a round-trip test.
- A test may cover multiple spec items, but each spec item is covered by at least one test.
- Status is tracked via CI gate results (Pass/Fail/Skipped), not manual checks.

## Gap-Check (Validation Review)

After writing Validation, verify every specification section and every walkthrough flow has at
least one corresponding test case, with explicit references to `4-specification.md`,
`3-walkthrough.md`, and/or `1-requirements.md`. Current coverage: 100% of SP/WT/NFR/SD items have
a test in the trace above.