agentleFS
radimsemradimsem/remindb/.claude/skills/add-integration-test/SKILL.md

add-integration-test

Skill125 starsChanged 7 months agoMITView on GitHub

Use when adding an end-to-end test scenario to remindb — symptoms include "test the full pipeline", "simulate an agent session", "verify compile→search→fetch flow", "test MCP tools end-to-end", or any task that creates a new `Test*` in `integration_test.go` / `mcp_integration_test.go` at the repo root. Distinct from per-package unit tests in `pkg/*/`.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. joelbarmettlerUZH/ultrainit.sh★ 8same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

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

    Reaching for store.Open directly: Use testutil.OpenTestDB(t) — it applies migrations, registers cleanup, and matches the assertion style …

    line 137
  2. Very specific:

    Hardcoding the absolute path to testdata/: Use filepath.Abs("testdata/<scenario>") like mcp_integration_test.go:14 — MemoryCompile …

    line 141

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Add an integration test

Integration tests live at the repo root in package remindb_test, not inside a pkg/. They exercise the full pipeline — a real store, real compiler, real MCP transport — against fixtures under testdata/. There are two flavors:

FlavorFileUse when
Direct APIintegration_test.goTesting compiler / query / store / transformer end-to-end without MCP
MCPmcp_integration_test.goTesting the user-visible tool surface as an agent would call it

Pick the flavor by the question you're asking. "Does the compiler emit the right shape from this fixture?" → direct. "Does an agent calling MemorySearch after MemoryCompile see the expected ranking?" → MCP.

Where it lands

FileWhat changes
integration_test.go or mcp_integration_test.goAdd a Test<Scenario> function
testdata/<scenario-name>/New fixture directory (only if existing fixtures don't match)

Fixture directories are flat namespaces (testdata/openclaw/, testdata/<your-scenario>/). One fixture set per scenario family; reuse aggressively.

The two helpers

Both files lean on package helpers — never reach for raw store.Open or raw mcp.NewServer in a test.

  • internal/testutil.OpenTestDB(t) — opens an in-memory :memory: SQLite store with migrations applied; auto-cleans on t.Cleanup. Use for direct-API tests.
  • internal/mcptest.NewEnv(t) — opens the test DB, wires a default-config server + tracker, connects an in-memory MCP transport, and exposes env.CallTool(t, name, args) and env.TextContent(t, result). Use for MCP tests.

Direct-API template

Mirror integration_test.go:TestOpenClawAgentWorkflow. Walk a real workflow stage by stage, log progress, assert at each stage:

package remindb_test

import (
    "context"
    "strings"
    "testing"

    "github.com/radimsem/remindb/internal/testutil"
    "github.com/radimsem/remindb/pkg/compiler"
    "github.com/radimsem/remindb/pkg/query"
)

func TestNewScenario(t *testing.T) {
    st := testutil.OpenTestDB(t)
    ctx := context.Background()

    // Stage 1: compile fixtures.
    result, err := compiler.CompileDir(ctx, st, "testdata/<scenario>", "<source-id>")
    if err != nil {
        t.Fatalf("CompileDir: %v", err)
    }
    if result.Added == 0 {
        t.Fatal("expected nodes from fixtures")
    }
    t.Logf("compiled: +%d ~%d -%d (%d total)", result.Added, result.Modified, result.Removed, result.Total)

    // Stage 2: query.
    engine := query.NewEngine(st)
    res, err := engine.Search(ctx, "<query>", 1000)
    if err != nil {
        t.Fatalf("Search: %v", err)
    }
    if len(res.Nodes) == 0 {
        t.Fatal("expected search hits")
    }
}

MCP template

Mirror mcp_integration_test.go:TestMcp_OpenClawAgent. The numbered-step structure is convention — each step represents one tool call an agent would make:

func TestMcp_NewScenario(t *testing.T) {
    env := mcptest.NewEnv(t)
    dir, _ := filepath.Abs("testdata/<scenario>")

    // 1. Compile.
    compileResult := env.CallTool(t, "MemoryCompile", map[string]any{
        "path":    dir,
        "message": "<scenario>-init",
    })
    text := env.TextContent(t, compileResult)
    if !strings.Contains(text, "compiled") {
        t.Fatalf("unexpected compile result: %s", text)
    }

    // 2. Search.
    searchResult := env.CallTool(t, "MemorySearch", map[string]any{
        "query":  "<keyword list>",
        "budget": 1000,
    })
    searchText := env.TextContent(t, searchResult)
    if searchText == "no results" {
        t.Fatal("expected results")
    }

    // 3. Further stages...
}

env.CallTool already calls t.Fatalf on transport / tool errors and logs both request and response preview to t.Log. You only assert the behavioral expectations.

Cleanup is automatic

testutil.OpenTestDB(t) and mcptest.NewEnv(t) both register t.Cleanup handlers — DB is dropped, MCP session is closed, in-memory transports are torn down. Don't write your own cleanup unless you allocate something outside these helpers (e.g., a t.TempDir() you wrote files into — that's also auto-cleaned by the testing framework, no manual work needed).

Fixtures under testdata/

testdata/ is the Go-recognized name; go test excludes it from build/lint. Place a fixture directory under it per scenario, with the same file extensions the parser recognizes (.md, .yaml, .json, .jsonl, .toon).

Name fixtures by concept (testdata/openclaw/, testdata/multi-format/), not by test (testdata/test_compile_1/). Multiple tests can share a fixture; one-test-per-fixture is anti-pattern.

Quick reference

Direct API:
1. integration_test.go              (Test<Scenario> with testutil.OpenTestDB)
2. testdata/<scenario>/             (fixtures matching parser-supported extensions)
3. go test ./... -run Test<Scenario>

MCP:
1. mcp_integration_test.go          (TestMcp_<Scenario> with mcptest.NewEnv)
2. testdata/<scenario>/             (same fixture rules)
3. go test ./... -run TestMcp_<Scenario>

Common mistakes

  • Reaching for store.Open directly. Use testutil.OpenTestDB(t) — it applies migrations, registers cleanup, and matches the assertion style of every other test. Direct store.Open skips migrations and gives you an empty schema.
  • Setting up the MCP transport by hand. pkg/mcp/server_test.go does this for unit-testing the server itself; integration tests should use mcptest.NewEnv(t). The handcrafted form has 6 lines of ceremony (NewInMemoryTransports, srv.Connect, mcp.NewClient, client.Connect, t.Cleanup for both, SetLoggingLevel if needed) — NewEnv collapses all of it.
  • Asserting on log output. env.CallTool logs request/response previews via t.Log for debugging. They're not part of the test contract; assert on env.TextContent(t, result) instead.
  • One fixture per test. Reuse testdata/openclaw/ for any scenario where its files are appropriate. New fixture directories are for genuinely new content shapes, not new test names.
  • Hardcoding the absolute path to testdata/. Use filepath.Abs("testdata/<scenario>") like mcp_integration_test.go:14 — MemoryCompile requires absolute paths.
  • Forgetting package remindb_test. Integration tests are external (use _test suffix on the package). They exercise the public API of multiple packages — they're not allowed to import unexported names.

Cross-references

  • .claude/rules/go-concise.md — early returns, error handling style, named function over closure-as-var
  • .claude/skills/add-mcp-tool/SKILL.md — when adding a tool, also extend mcp_integration_test.go with a scenario that exercises it through env.CallTool
  • .claude/skills/add-store-query/SKILL.md — when adding a query, the unit test goes in pkg/store/store_test.go; an integration test only makes sense if it changes a multi-package workflow

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.