/openlore-write-tests

name: openlore-write-tests
description: Write and run real tests for a function or spec scenario after reading implementation and contract evidence. Use when asked to add, improve, or repair tests without stubs or placeholders.

openlore: Write Tests

When to use this skill

Trigger this skill when the user wants to **write real tests** for a function, module, or spec scenario, with phrasings like:

• "write tests for X"
• "add test coverage for Y"
• "what spec scenarios are untested?"
• "implement the test for this scenario"
• explicit command `/openlore-write-tests`

**The rule**: read the implementation and spec contract before writing a single assertion. No `expect(true).toBe(true)`, no stubs, no placeholders.

**Prerequisite**: openlore analysis must exist (`openlore analyze` has been run). If `orient` returns `"error": "no cache"` → run `openlore analyze` first, then retry.

---

Step 1 — Identify target + detect framework

Ask the user: 1. **Target** — a function name, file path, spec scenario, or domain to test. If unsure, skip to Step 1b. 2. **`$PROJECT_ROOT`** — project root directory.

**Step 1b — Find untested scenarios (if no target given)**

Call the openlore MCP tool `get_test_coverage` with `{"directory": "$PROJECT_ROOT"}`.

Present the top 5 uncovered scenarios to the user, ranked by spec importance. Ask which to implement first.

**Step 1c — Detect test framework**

Scan the project root for framework config files:

| File found | Framework | |---|---| | `vitest.config.*`, `vitest.config.ts` | Vitest — runner: `npx vitest run <file>` | | `jest.config.*` | Jest — runner: `npx jest <file>` | | `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` | pytest — runner: `pytest <file> -v` | | `CMakeLists.txt` with `enable_testing()`, `*.test.cpp` | CTest/GTest — runner: build + `ctest` | | `go.mod` | Go test — runner: `go test ./...` |

Store as `$TEST_RUNNER`. If ambiguous, ask the user.

---

Step 2 — Orient

Call the openlore MCP tool `orient` with:

{
  "directory": "$PROJECT_ROOT",
  "task": "write tests for $TARGET",
  "limit": 5
}

Extract:

• **`$TARGET_FILE`** — the file containing the function(s) to test
• **`$EXISTING_TEST_FILE`** — nearby test file, if any (e.g. `foo.test.ts`, `test_foo.py`, `foo_test.go`)
• **`$SPEC_DOMAIN`** — the spec domain associated with the target

---

Step 3 — Read implementation + spec contract

**This step is mandatory. Do not write any test before completing it.**

**3a — Read the function body**

Call the openlore MCP tool `get_function_body` with:

{
  "directory": "$PROJECT_ROOT",
  "symbol": "$TARGET_FUNCTION",
  "filePath": "$TARGET_FILE"
}

Identify:

• What the function takes as input, what it returns
• What external dependencies it calls (filesystem, network, DB, LLM, subprocess)
• What invariants are visible (guards, throws, early returns)

**3b — Find the spec contract (if specs exist)**

Call the openlore MCP tool `search_specs` with:

{
  "directory": "$PROJECT_ROOT",
  "query": "$TARGET — expected behaviour",
  "limit": 5
}

For each matching spec scenario, note:

• The **GIVEN / WHEN / THEN** clauses — these become the test body
• The scenario name — this becomes the `it()` / `def test_` / `TEST()` description

If no specs exist, infer the contract from the function signature, docstring, and call sites. Document the inferred contract explicitly before writing any test.

**3c — Absorb local test conventions**

If `$EXISTING_TEST_FILE` exists, read it. Extract:

• Mock setup pattern (`vi.mock`, `unittest.mock.patch`, `gmock`, etc.)
• Fixture or factory helpers
• Import path style (relative vs absolute)
• Describe/class/suite structure

If no test file exists nearby, find the closest test file in the project tree and read that instead.

---

Step 4 — Write tests

Write (or append to) `$EXISTING_TEST_FILE` (or create `<name>.test.ts` / `test_<name>.py` / `<name>_test.go` next to the source file).

Rules — enforced without exception

1. **No placeholder assertions** — `expect(true).toBe(true)`, `assert True`, `EXPECT_TRUE(true)`, `self.assertTrue(True)` are forbidden. Every assertion must test real return values or side effects.

2. **One test = one scenario** — each `it()` / `def test_` / `TEST()` maps to one GIVEN/WHEN/THEN clause. Use the spec scenario name (or a descriptive contract statement) as the test description.

3. **Annotation tag (mandatory)** — place a coverage tag on the line immediately above each `describe` / class / suite block so `openlore test --coverage` can track it:

• TypeScript/JS: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO","specFile":"openspec/specs/$DOMAIN/spec.md"}`
• Python: `# openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`
• C++/Go: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`

If no spec scenario exists (contract inferred), omit the tag.

4. **Mock only system boundaries** — mock filesystem, network, LLM API, DB connections, and external processes. Do not mock the function under test, its pure helpers, or in-memory logic.

5. **One suite per function** — `describe` / class / suite named after the function. Use nested blocks for distinct concerns (happy path, error path, edge cases).

6. **At least one edge case** — empty input, null/None/nullptr, maximum value, or an error path must be included for every function tested.

7. **Small model constraint** — if the test file exceeds 200 lines, split into multiple files grouped by concern. Each file must be independently runnable.

Structure reference (adapt to the detected framework)

// TypeScript / Vitest
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { $TARGET_FUNCTION } from '../$TARGET_FILE';

vi.mock('../$DEPENDENCY', () => ({ ... }));

// openlore: {"domain":"$DOMAIN","requirement":"$REQUIREMENT","scenario":