natsnet/docs/plans/2026-02-27-batch-0-implementable-tests-design.md

Batch 0 Implementable Tests Design

Date: 2026-02-27
Scope: Plan how to port/implement Batch 0 unit tests only (no execution in this document).

Problem

Batch 0 is defined as: deferred tests whose feature dependencies are already verified/complete/n_a.
However, current tracker output is inconsistent:

• batch show 0 reports Tests: 0
• report summary reports 2640 deferred unit tests
• direct DB query shows 553 deferred tests already satisfy Batch 0 dependency rules
• all 553 have dotnet_class + dotnet_method mappings and method names already present in test source

This means Batch 0 implementation planning must treat the DB batch_tests mapping as stale and use a dependency query as the source of truth.

Context Findings

Command Findings

• batch show 0 --db porting.db: Batch metadata exists but has no mapped tests.
• batch list --db porting.db: total mapped tests across batches = 2087.
• report summary --db porting.db: deferred tests = 2640.
• Gap: 2640 - 2087 = 553 deferred tests are currently unassigned to any batch.

Source-of-Truth Query (Batch 0 Candidates)

WITH implementable AS (
  SELECT t.id
  FROM unit_tests t
  WHERE t.status = 'deferred'
    AND EXISTS (
      SELECT 1
      FROM dependencies d
      JOIN features f ON f.id = d.target_id AND d.target_type = 'feature'
      WHERE d.source_type = 'unit_test' AND d.source_id = t.id
    )
    AND NOT EXISTS (
      SELECT 1
      FROM dependencies d
      JOIN features f ON f.id = d.target_id AND d.target_type = 'feature'
      WHERE d.source_type = 'unit_test'
        AND d.source_id = t.id
        AND f.status NOT IN ('verified', 'complete', 'n_a')
    )
)
SELECT COUNT(*) FROM implementable; -- 553

Candidate Distribution (553 tests)

All 553 are in module server and currently land in dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.Impltests.cs.

Largest classes:

• JetStreamEngineTests (89)
• MonitoringHandlerTests (76)
• MqttHandlerTests (56)
• LeafNodeHandlerTests (47)
• NatsConsumerTests (35)
• JwtProcessorTests (28)
• RouteHandlerTests (25)

Approaches

Approach A: Use Existing batch_tests Mapping Only

• Work only from batch show 0.
• Pros: Uses existing CLI flow exactly.
• Cons: Batch 0 is empty today, so this blocks all useful work and misses 553 valid candidates.

Approach B: Query-Driven Batch 0 (No DB Mapping Changes)

• Treat the SQL dependency query as authoritative for execution order/status updates.
• Pros: No batch table mutation; can start immediately.
• Cons: batch show 0 remains misleading; no built-in batch completion visibility.

Approach C (Recommended): Query-Driven Execution + Batch 0 Mapping Reconciliation

• First, reconcile batch_tests for Batch 0 from dependency query.
• Then implement tests by class waves using a manifest generated from the same query.
• Pros: Correct batch visibility, supports batch show 0, preserves workflow consistency.
• Cons: One upfront tracker-maintenance step.

Recommended Design

1. Batch 0 Candidate Manifest

Create a reproducible manifest (CSV/SQL output) containing:

• test_id
• dotnet_class
• dotnet_method
• go_file
• go_method

The manifest is regenerated from DB each session to avoid stale lists.

2. Batch Mapping Reconciliation

Insert missing candidate tests into batch_tests(batch_id=0) only when absent.
Do not reassign already-mapped tests in other batches.

3. Implementation Model

Port tests class-by-class in ImplBacklog files first (lowest-risk), then optionally move mature tests to domain folders later.

Per test workflow:

1. Open Go test body at mapped go_file + go_method.
2. Classify test as:
   • implementable-unit (no running server/cluster required)
   • runtime-blocked (needs real server/cluster infra) -> keep deferred, add note
3. Replace placeholder/assertion-only body with behavior-faithful xUnit 3 + Shouldly test.
4. Run method and class filters.
5. Update tracker status only after green test evidence.

4. Wave Sequencing

Order by lowest infra risk first:

1. Accounts/Auth/JWT/Options/reload
2. Routes/Gateways/Leaf/WebSocket
3. Events/Monitoring/MsgTrace/Server core
4. JetStream lightweight deterministic tests
5. JetStream heavy + MQTT + concurrency edge cases

5. Verification Gates

• Gate 1: Method-level run passes after each test port.
• Gate 2: Class-level run passes before status updates.
• Gate 3: Wave-level run passes before commit.
• Gate 4: End-of-batch query returns zero remaining implementable deferred tests.

Error Handling and Risk Controls

• If Go test requires unavailable runtime infra, do not force a brittle port; keep deferred with explicit note.
• If ported test reveals feature regression, stop and create a feature-fix branch of work before marking test verified.
• Keep DB updates idempotent: only update statuses for IDs proven by passing runs.
• Avoid mass test batch-update ... verified without per-class pass evidence.

Success Criteria

• Batch 0 mapping reflects true implementable set (or documented query-based equivalent).
• All implementable unit tests in the set are ported and passing.
• Runtime-blocked tests remain deferred with explicit reason notes.
• report summary and Batch 0 progress trend down deterministically after each wave.

Non-Goals

• No server/cluster integration infrastructure build-out in this batch.
• No refactoring of production server code except where discovered test failures require follow-up work.
• No attempt to complete non-Batch-0 deferred tests.