stefan-kp
55 lines
2.0 KiB
Markdown
55 lines
2.0 KiB
Markdown
# Tactical and Gambit Fixture Sets
|
||
|
||
This directory collects JSON fixtures for automated regression tests and training data generation.
|
||
Each file contains narrowly scoped cases for a single tactical motif or gambit family so that Jest
|
||
or other tooling can load them directly without hard-coding FEN strings in test suites.
|
||
|
||
## File naming
|
||
- `tactics/<pattern>.json` – Examples for one tactical motif. Each file follows the same schema.
|
||
- `gambits.json` – Openings that should be recognised by move-sequence matching.
|
||
|
||
## Common schema
|
||
Every tactical case shares the following shape:
|
||
|
||
```json
|
||
{
|
||
"patternType": "PIN",
|
||
"description": "Short explanation of the motif and what the move achieves.",
|
||
"cases": [
|
||
{
|
||
"id": "unique-string",
|
||
"initialFen": "...",
|
||
"sideToMove": "white",
|
||
"bestMove": { "san": "Bb5", "uci": "f1b5" },
|
||
"resultingFen": "...",
|
||
"expectedPattern": {
|
||
"type": "PIN",
|
||
"side": "white",
|
||
"attackerSquares": ["b5"],
|
||
"targetSquares": ["c6"],
|
||
"keySquares": ["e8"],
|
||
"explanationKey": "pin_to_king"
|
||
},
|
||
"context": "Optional PGN fragment or free-text rationale.",
|
||
"tags": ["opening", "classical"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
This layout aligns with the `TacticalPattern` interface defined in the library contract and keeps
|
||
enough metadata for round-trip testing: the move that produces the tactic, the resulting position,
|
||
and the expected pattern payload.
|
||
|
||
## Using the fixtures in tests
|
||
- Load the JSON files and iterate through `cases` to drive `detectTactics`,
|
||
`findTacticalOpportunitiesForSide`, or higher-level exercise generators.
|
||
- The `initialFen` represents the position **before** the critical move is played.
|
||
- Apply `bestMove` to reach `resultingFen`, then assert that the reported pattern matches
|
||
`expectedPattern`.
|
||
|
||
## Adding more cases
|
||
When adding new fixtures, prefer minimal positions that isolate the intended motif so failures
|
||
are easy to debug. Include a short `context` note so the scenario can be recreated or visualised
|
||
quickly when a test fails.
|