natsClient_JS/docs/6-validation.md

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.