agentleFS
clay-goodclay-good/OpenLore/skills/openlore-write-tests/SKILL.md

openlore-write-tests

Skill365 starsChanged 6 months agoMITView on GitHub

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.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. About 0 are common, 11 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    The rule: read the implementation and spec contract before writing a single assertion.

    line 18
  2. Very specific:

    If orient returns "error": "no cache" → run openlore analyze first, then retry.

    line 22
  3. Very specific:

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

    line 34
  4. Very specific:

    Call the openlore MCP tool orient with:

    line 56
  5. Distinctive:

    If no specs exist, infer the contract from the function signature, docstring, and call sites.

    line 107
  6. Distinctive:

    Document the inferred contract explicitly before writing any test.

    line 108
  7. Very specific:

    If $EXISTING_TEST_FILE exists, read it.

    line 112
  8. Distinctive:

    Import path style (relative vs absolute)

    line 115
  9. Distinctive:

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

    line 118
  10. Very specific:

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

    line 124
  11. Distinctive:

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

    line 140
  12. Distinctive:

    Use nested blocks for distinct concerns (happy path, error path, edge cases).

    line 146
  13. Very specific:

    Run the test file with $TEST_RUNNER.

    line 197
  14. Distinctive:

    Do not weaken assertions to make tests pass.

    line 206
  15. Very specific:

    Never write expect(true).toBe(true), assert True, or equivalent placeholder assertions

    line 223
  16. Distinctive:

    Never skip Step 3 — the implementation read and spec contract are the test source of truth

    line 224
  17. Distinctive:

    Never mock the function under test itself

    line 225
  18. Distinctive:

    Never weaken an assertion to make a test pass — fix the implementation or the expectation

    line 226
  19. Very specific:

    If get_test_coverage shows the scenario is already covered, report it and stop

    line 227
  20. Distinctive:

    Do not refactor the implementation as part of this skill — open a separate task

    line 228

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 foundFramework
vitest.config.*, vitest.config.tsVitest — runner: npx vitest run <file>
jest.config.*Jest — runner: npx jest <file>
pytest.ini, pyproject.toml (with [tool.pytest]), setup.cfgpytest — runner: pytest <file> -v
CMakeLists.txt with enable_testing(), *.test.cppCTest/GTest — runner: build + ctest
go.modGo 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":"$SCENARIO","specFile":"openspec/specs/$DOMAIN/spec.md"}
describe('$TARGET_FUNCTION', () => {
  beforeEach(() => { vi.resetAllMocks(); });

  describe('$SCENARIO_NAME', () => {
    it('should $EXPECTED_BEHAVIOUR when $CONDITION', () => {
      // GIVEN
      // WHEN
      const result = $TARGET_FUNCTION($INPUT);
      // THEN
      expect(result).toEqual($EXPECTED);
    });
  });
});
# Python / pytest
import pytest
from unittest.mock import patch, MagicMock
from $MODULE import $TARGET_FUNCTION

# openlore: {"domain":"$DOMAIN","requirement":"$REQUIREMENT","scenario":"$SCENARIO"}
class Test$TargetFunction:
    def test_$scenario_name_when_$condition(self):
        # GIVEN / WHEN / THEN
        result = $target_function($input)
        assert result == $expected

Step 5 — Run and fix

Run the test file with $TEST_RUNNER. Iterate until all tests pass.

OutcomeAction
All greenProceed to Step 6
Failure in new testDiagnose: is the assertion wrong, or is there a real bug? Fix the assertion if the expectation was incorrect. If a real bug is revealed, do not weaken the assertion — report the bug instead.
Failure in pre-existing testStop. Fix the regression before adding more tests.
Test can't compile / importFix the import path, mock setup, or dependency injection before retrying.

Do not weaken assertions to make tests pass. A test that masks a bug is worse than no test.


Step 6 — Coverage check

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

Report:

  • Which spec scenarios are now covered (new)
  • Which scenarios remain uncovered in $SPEC_DOMAIN
  • Whether any hub functions in $SPEC_DOMAIN are still untested (high-value next targets)

Absolute constraints

  • Never write expect(true).toBe(true), assert True, or equivalent placeholder assertions
  • Never skip Step 3 — the implementation read and spec contract are the test source of truth
  • Never mock the function under test itself
  • Never weaken an assertion to make a test pass — fix the implementation or the expectation
  • If get_test_coverage shows the scenario is already covered, report it and stop
  • Do not refactor the implementation as part of this skill — open a separate task

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.