Tester

Source file: internal/tester/tester.go

The tester wraps forge test and parses JSON output into structured suite/case results. It supports path, contract, and test name filtering, and returns partial results when some tests fail.

Design decisions

Forge test with JSON output

The tester runs forge test --json and parses the output. It supports both single-object JSON and NDJSON (one line per suite) formats, handling the output variation across forge versions.

Filtering

Three optional filters narrow the test run:

Filter	Forge flag	Example
`match_path`	`--match-path`	`test/MyToken.t.sol`
`match_contract`	`--match-contract`	`MyTokenTest`
`filter`	`--match-test`	`testTransfer`

Structured output

Test results are parsed into a hierarchical structure:

TestResponse
  ├── Passed: int
  ├── Failed: int
  └── Suites: []TestSuiteResult
        ├── File: string
        ├── Passed/Failed/Skipped: int
        └── Cases: []TestCaseResult
              ├── Name: string
              ├── Status: "Success" | "Failure"
              ├── Reason: string (failure details)
              ├── Gas: uint64 (unit gas or fuzz mean gas)
              └── Duration: string

Partial results on failure

When tests fail, the tester returns the envelope with ok: false but populates data with the suite results. This lets agents see exactly which tests failed and why without a second round-trip.

Timeout

The forge subprocess has a 30-minute timeout, generous for large test suites.

Error codes

Code	Meaning
`TEST_FORGE_FAILED`	`forge test` subprocess failed (non-zero exit, timeout, no output)
`TEST_ASSERTION_FAILED`	One or more tests failed (partial results in `data`)
`INVALID_REQUEST`	Missing `project_root`

Modifying the tester

What to change	Where
Add filter flag	`internal/tester/tester.go` - `Test` method args
Change timeout	`internal/tester/tester.go` - `RunWithTimeout` call (30 min)
Add gas reporting	`pkg/types/test.go` - `TestCaseResult`
Parse coverage output	New method in `internal/tester/`