# Test Quality Standard

Status: normative for every NexusCRM release-boundary repository.

## Outcome

Tests exist to detect plausible product failures at the boundary that owns the
invariant. Test count and line coverage are not goals by themselves.

The decision question is:

> Would this test fail for a plausible production defect while remaining stable
> across an equivalent correct implementation?

If the answer is no, nominal coverage is not a reason to keep the test.

## Remove implementation-shaped tests

A test is a removal candidate when it has little independent fault-detection
value and does one or more of the following:

- pins SQL text, regular expressions, aliases, whitespace, statement order, or
  transaction choreography that is not itself a public contract;
- scripts database queries and returned rows, then reasserts those same rows;
- copies canonical schema, catalog, metadata, lifecycle state, hashes, or other
  facts owned elsewhere;
- asserts private sentinels, helper order, internal branches, or call order;
- uses the same implementation path to create and verify state;
- simulates TiDB locking, isolation, rollback, crash recovery, or distributed
  behavior with an in-memory script or normal helper return;
- duplicates a stronger real-database, process-boundary, integration, or
  end-to-end proof without improving fault localization.

Delete these tests instead of mechanically porting them to another mock.

## Retain tests with an independent oracle

Keep a test when it names a stable invariant, observes the owning boundary, and
can catch a plausible bad mutation or incident class. Examples include:

- pure transformation and validation tests whose inputs and outputs are the
  contract;
- fail-closed guards that prove invalid input cannot reach an external effect;
- focused fault injection at a small, stable external boundary;
- canonical catalog tests that read the owning source rather than copying it;
- real TiDB tests for query semantics, constraints, transactions, locking,
  isolation, migration, rollback, retry, and recovery;
- black-box API, service, process, and pack-assembly journeys.

SQL text may be asserted only when the emitted SQL is itself the owned output,
and the test states the database behavior or compatibility contract that makes
the exact shape significant.

## Replacement rule

Replace only important guarantees, at the smallest realistic boundary that owns
them:

- use canonical schema/bootstrap rather than copied `_System_*` DDL;
- use real TiDB for persistence and concurrency claims;
- use real process interruption and restart for recovery claims;
- use service or API outcomes for cross-module behavior;
- use actual Catalog, pack, and Runtime assembly for L0/L1/L2 compatibility.

A realistic test that can silently skip is not proof in a required gate. Local
and CI runners must make required walking slices fail closed when TiDB or another
declared dependency is unavailable.

## Review record

For every retained implementation-adjacent test, reviewers must be able to name:

1. the stable invariant;
2. its owning component;
3. one plausible defect the test detects;
4. why an equivalent correct implementation would still pass.

Record shared realistic-harness gaps instead of filling them with local fakes.