52 lines
4.1 KiB
Markdown
52 lines
4.1 KiB
Markdown
---
|
|
name: semantics-testing
|
|
description: 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.]** |