Skip to main content

GOV 05 TESTING

This page embeds the canonical rule text and adds rule-specific commentary to explain why each section exists.

Governance: Testing​

Commentary: Frames testing as the proof system for governed implementation.

Core Testing Principle​

Tests are proof of claims, not ceremony.

Each important claim should map to verifiable evidence.

Commentary: Requires tests to answer whether the intended behavior actually works.

Test Design Standards​

  • prefer behavior-focused tests over implementation-detail tests
  • include success and failure paths
  • include edge cases for high-risk logic
  • keep tests deterministic and repeatable

Commentary: Keeps tests focused on meaningful behavior, failure modes, and regression risk.

Testing Layers (use what fits scope)​

  • Unit: isolated logic correctness
  • Integration: component boundaries and contracts
  • End-to-end: user-critical workflows
  • Regression: prevent behavior drift

Not every change needs every layer, but critical paths must be covered.

Commentary: Lets teams choose the right validation layer without pretending every change needs the same test shape.

Unit-Test Expectations​

Unit tests are expected when the scoped behavior can be proved meaningfully at the isolated-logic layer, especially for:

  • pure functions, transforms, selectors, parsers, validators, and mappers
  • branching business logic with clear input/output behavior
  • bug fixes where the failure can be reproduced below the integration/UI layer
  • boundary conditions and edge cases in deterministic code paths

Unit tests are not sufficient by themselves when the governed claim depends on:

  • persistence, refresh, sync, or deletion behavior
  • cross-component or cross-service contracts
  • user-visible workflows, permissions, or navigation
  • environment/runtime wiring, startup, deployment, or release-readiness behavior

When unit tests are the right layer, they should be preferred over slower broad tests for proving isolated logic. When the claim extends beyond isolated logic, pair unit coverage with the higher-layer evidence the claim actually needs.

Commentary: Defines when small focused tests should pin logic and edge-case behavior.

Test-to-Intent Traceability​

For governed delivery, link tests back to:

  • OpenSpec requirement IDs,
  • acceptance criteria,
  • or explicit behavior statements.

OpenSpec-first rule:

  • if required behavior is not represented in OpenSpec, add/update requirement IDs before marking coverage complete.

Commentary: Connects tests back to requirements so passing checks prove the right thing.

Test Execution Expectations​

For each meaningful test run, explicitly consider:

  • the exact claim / requirement / acceptance criterion under test
  • which scenario classes were exercised
  • which scenario classes were blocked, deferred, or not applicable
  • what kind of evidence was produced
  • whether the evidence directly proves the claim or only a proxy
  • what remains unverified and what follow-up artifact was created

Commentary: Requires test results to be captured honestly, including failures and skipped checks.

Scenario Coverage Expectations​

Consider these scenario classes where relevant:

  • happy path
  • invalid input
  • empty state
  • loading state
  • error state
  • cancel/back-out path
  • persistence/refresh behavior
  • downstream side effects
  • role/permission variation
  • keyboard/accessibility path

Not every change needs every scenario class, but the execution record should make coverage boundaries visible.

Commentary: Pushes validation beyond the happy path into states users actually encounter.

Result Classification​

Meaningful test outcomes should be classifiable as:

  • Verified
  • Invalidated
  • Blocked
  • Deferred
  • Not applicable

This helps prevent weak “green enough” reporting.

Commentary: Makes validation outcomes explicit enough for a reviewer to trust or challenge.

Proof Strength​

Evidence should be judged honestly:

  • direct proof — clearly proves the intended behavior
  • partial proof — proves only part of the claim
  • surrogate-only proof — proves a proxy, not the actual outcome

Passing build output, a success toast, or a 200 response is not always direct proof of the intended behavior.

Commentary: Ranks evidence quality so weak signals are not reported as strong proof.

Persistence and Post-Action Proof​

When work changes persisted, synced, deleted, or otherwise durable state, verification should check the post-action reality where relevant:

  • refresh/reload state
  • source-of-truth state
  • downstream consumer state
  • deletion/removal persistence
  • sync behavior after the action

UI-only success must not be treated as sufficient proof for mutation-heavy work.

Commentary: Requires checks that state survives the action paths users rely on.

Execution Expectations​

  • run targeted tests during iteration
  • run appropriate regression checks before completion
  • add or update unit tests when isolated logic is changed and unit coverage is the right proving layer
  • do not treat unit tests as sufficient when the governed claim depends on higher-layer behavior
  • capture failing output when blocked
  • avoid marking complete without evidence
  • generated tests only count when they actually prove the intended behavior or requirement
  • passing tests are evidence only when the asserted behavior matches the governed claim
  • if meaningful coverage is missing, create follow-up work instead of silently treating the gap as acceptable

Commentary: Defines how test runs should be invoked, recorded, and explained during delivery.

Test Quality Anti-Patterns​

  • flaky tests accepted as "good enough"
  • broad snapshot assertions without intent
  • coverage metrics used without behavioral relevance
  • tests that pass but do not prove the requirement
  • partial coverage reported as full validation
  • surrogate-only proof reported as direct proof

Commentary: Calls out tests that inflate confidence without covering real behavior.