# Query Doc → Test Coverage Parity Check

## Context

Module: {{MODULE_NAME}}
Query docs: {{QUERY_DOCS}}
Test code: {{QUERY_TEST_CODE}}

## Instructions

1. Read ALL query docs at the paths above
2. Read ALL test code files at the paths above
3. For each query doc, extract process flow branches, error scenarios, and edge cases
4. For each test file, extract test case descriptions and assertions
5. Run every parity check below against each query
6. Return results as JSON per the Output Format section

## Extraction: Query Docs

From each query doc, extract:

### Process Flow Branches

From the mermaid flowchart, identify each decision node and its outcomes:

- Decision: "Permission check?" → Authorized path, Unauthorized path
- Decision: "Entity exists?" → Found path, Not found path
- Decision: "Scope valid?" → Valid scope path, Invalid scope path
- Each terminal node = one expected test case

### Error Scenarios

From the Error Scenarios section:

- Error code + condition = one expected error test case

### Null/Empty Return Paths

From the process flow, identify "not found → return null" or "no results → return empty array" patterns:

- These need explicit test cases

### Pagination Scenarios

For paginated queries:

- Has more results → `hasNextPage: true`
- Last page → `hasNextPage: false`
- Empty results → empty items array

## Extraction: Test Code

From each test file (`query/*.test.ts`), extract:

- **Test descriptions**: `it("...")` or `test("...")` strings
- **Error assertions**: checks for specific error types/codes
- **Happy path tests**: tests that verify successful outcomes
- **Null/empty result tests**: tests that verify not-found or empty list handling
- **Authorization tests**: tests that verify permission and scope checks
- **Fixture usage**: which fixtures are used

See [testing.md](../../erp-kit-shared/references/testing.md) for canonical testing patterns.

## Parity Checks

For each query:

| Check ID                | Question                                                     |
| ----------------------- | ------------------------------------------------------------ |
| process_flow_coverage   | Does each branch in process flow have a test case?           |
| error_scenario_tests    | Does each documented error scenario have a test assertion?   |
| happy_path_tests        | Are success paths tested?                                    |
| null_empty_result_tests | If doc shows "not found → null" or "empty → []", is tested? |
| authorization_tests     | Are permission and scope check paths tested?                 |
| pagination_tests        | If doc describes pagination, are boundary cases tested?      |

### How to Check

1. Count process flow branches from query doc flowchart
2. Count test cases in corresponding test file
3. Map each branch to a test case by description/assertion
4. Identify any branches without corresponding tests

## Common Gap Patterns

- **Uncovered process branches**: Flowchart branch has no test
- **Missing error tests**: Error scenario has no assertion
- **Missing null/empty tests**: "Not found → null" path untested
- **Missing authorization tests**: Permission or scope check untested
- **Missing pagination edge cases**: hasNextPage boundary untested
- **Missing filter combination tests**: Search queries with multiple filters untested
- **Test without doc branch**: Test exists but doesn't map to documented flow (potential doc gap)

## Output Format

Return a JSON object:

```json
{
  "check_type": "query-doc-test-parity",
  "module": "{{MODULE_NAME}}",
  "gaps": [...],
  "inconsistencies": [...],
  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
}
```

See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.