update

2026-09-18 22:03:10 +07:00
parent b57403d373
commit 743928c63b
8 changed files with 725 additions and 43 deletions
@@ -0,0 +1,64 @@
+# 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.