ss-tools/.kilo/skills/semantics-testing/SKILL.md

name, description

name	description
semantics-testing	Core protocol for Test Constraints, External Ontology, Graph Noise Reduction, and Invariant Traceability.

[DEF:Std:Semantics:Testing]

@COMPLEXITY: 5

@PURPOSE: Core protocol for Test Constraints, External Ontology, Graph Noise Reduction, and Invariant Traceability.

@RELATION: DEPENDS_ON -> [Std:Semantics:Core]

@INVARIANT: Test modules must trace back to production @INVARIANT tags without flooding the Semantic Graph with orphan nodes.

0. QA RATIONALE (LLM PHYSICS IN TESTING)

You are an Agentic QA Engineer. Your primary failure modes are:

1. The Logic Mirror Anti-Pattern: Hallucinating a test by re-implementing the exact same algorithm from the source code to compute expected_result. This creates a tautology (a test that always passes but proves nothing).
2. Semantic Graph Bloat: Wrapping every 3-line test function in a Complexity 5 contract, polluting the GraphRAG database with thousands of useless orphan nodes. Your mandate is to prove that the @POST guarantees and @INVARIANT rules of the production code are physically unbreakable, using minimal AST footprint.

I. EXTERNAL ONTOLOGY (BOUNDARIES)

When writing code or tests that depend on 3rd-party libraries or shared schemas that DO NOT have local [DEF] anchors in our repository, you MUST use strict external prefixes. CRITICAL RULE: Do NOT hallucinate [DEF] anchors for external code.

1. External Libraries ([EXT:Package:Module]):
   • Use for 3rd-party dependencies.
   • Example: @RELATION: DEPENDS_ON ->[EXT:FastAPI:Router] or [EXT:SQLAlchemy:Session]
2. Shared DTOs ([DTO:Name]):
   • Use for globally shared schemas, Protobufs, or external registry definitions.
   • Example: @RELATION: DEPENDS_ON -> [DTO:StripeWebhookPayload]

II. TEST MARKUP ECONOMY (NOISE REDUCTION)

To prevent overwhelming Semantic Graph, test files operate under relaxed complexity rules:

1. Short IDs: Test modules MUST use concise IDs (e.g., [DEF:PaymentTests:Module]), not full file paths.
2. Root Binding (BINDS_TO): Do NOT map the internal call graph of a test file. Instead, anchor the entire test suite or large fixture classes to the production module using: @RELATION: BINDS_TO -> [DEF:TargetModuleId].
3. Complexity 1 for Helpers: Small test utilities (e.g., _setup_mock, _build_payload) are C1. They require ONLY [DEF]...[/DEF] anchors. No @PURPOSE or @RELATION allowed.
4. Complexity 2 for Tests: Actual test functions (e.g., test_invalid_auth) are C2. They require [DEF]...[/DEF] and @PURPOSE. Do not add @PRE/@POST to individual test functions.

III. TRACEABILITY & TEST CONTRACTS

In the Header of your Test Module (or inside a large Test Class), you MUST define the Test Contracts. These tags map directly to the @INVARIANT and @POST tags of the production code you are testing.

• @TEST_CONTRACT: [InputType] -> [OutputType]
• @TEST_SCENARIO: [scenario_name] -> [Expected behavior]
• @TEST_FIXTURE: [fixture_name] -> [file:path] | INLINE_JSON
• @TEST_EDGE: [edge_name] -> [Failure description] (You MUST cover at least 3 edge cases: missing_field, invalid_type, external_fail).
• The Traceability Link: @TEST_INVARIANT: [Invariant_Name_From_Source] -> VERIFIED_BY: [scenario_1, edge_name_2]

IV. ADR REGRESSION DEFENSE

The Architectural Decision Records (ADR) and @REJECTED tags in production code are constraints. If the production [DEF] has a @REJECTED: [Forbidden_Path] tag (e.g., @REJECTED: fallback to SQLite), your Test Module MUST contain an explicit @TEST_EDGE scenario proving that the forbidden path is physically unreachable or throws an appropriate error. Tests are the enforcers of architectural memory.

V. ANTI-TAUTOLOGY RULES

1. No Logic Mirrors: Use deterministic, hardcoded fixtures (@TEST_FIXTURE) for expected results. Do not dynamically calculate expected = a + b to test an add(a, b) function.
2. Do Not Mock The System Under Test: You may mock [EXT:...] boundaries (like DB drivers or external APIs), but you MUST NOT mock the local [DEF] node you are actively verifying.

[SYSTEM: END OF TESTING DIRECTIVE. ENFORCE STRICT TRACEABILITY.]