# TestBench — start here

A .NET test workstation that runs xUnit tests **and archives your entire source tree on every
run**, so that when several agents (or one distracted human) edit the same working tree, a state
that worked can always be found again — what passed, what broke it, who overwrote it, and the
exact bytes to get it back. No commits required.

Three front ends over one core, all sharing one history database:

| | What | For |
| --- | --- | --- |
| `testbench.exe` | Command-line tool | Scripting, CI, quick checks |
| `TestBench.Mcp.exe` | MCP server (stdio) | AI agents editing code |
| `TestBench.Wpf.exe` | Desktop window | Reviewing a session by hand |

Full feature reference: [CAPABILITIES.md](CAPABILITIES.md). Known-issues worklist:
[DEFICIENCIES.md](DEFICIENCIES.md).

---

## Install

### On a machine with this repository

```bash
powershell -ExecutionPolicy Bypass -File TestBench.Core\publish.ps1 -Zip
```

That writes `.publish\TestBench\` (three app folders plus this README) and
`.publish\TestBench-portable.zip`.

### On a machine without the repository

1. Copy `TestBench-portable.zip` over and extract it to `%USERPROFILE%\TestBench\bin`.
2. That's it. The apps are self-contained — no .NET install needed.

The tools store all state (history database, logs, replays) under `%USERPROFILE%\TestBench\`,
so putting the binaries in `bin` under the same root keeps everything in one place.

Optionally add `%USERPROFILE%\TestBench\bin\testbench` to `PATH` so `testbench` works anywhere.

---

## Register the MCP server with Claude Code

```bash
claude mcp add --scope user testbench -- %USERPROFILE%\TestBench\bin\mcp\TestBench.Mcp.exe
```

`--scope user` makes the tools available in every repository on the machine, which is what you
want: the server takes the project path per call, so one registration serves all projects.

Or per project, in the repo's `.mcp.json` (forward slashes work; substitute your user folder):

```json
{
  "mcpServers": {
    "testbench": {
      "command": "C:/Users/<you>/TestBench/bin/mcp/TestBench.Mcp.exe"
    }
  }
}
```

**Point the registration at the published exe, not `dotnet run`.** `dotnet run` writes build
output to stdout — the JSON-RPC channel — and it cannot start at all while the working tree does
not compile, which is exactly when you need your history.

---

## First five minutes (CLI)

```bash
testbench discover -p Path\To\Your.Tests
```

```bash
testbench run -p Path\To\Your.Tests --agent you --note "baseline before refactor"
```

```bash
testbench why -t Full.Name.Of.A.FailingTest
```

`discover` is static (Roslyn) — it works even when the project doesn't compile. `run` executes
the suite, archives the full source tree, and reports anything that drifted or got overwritten.
`why` answers "what changed since this test last passed".

**The archive only knows about states it saw.** The value of every history feature — lost-update
detection, drift, bisect, recovery — is proportional to how often runs happen. Start running
through TestBench *now*, not after something goes missing.

---

## Make your agents use it

An agent that shells out to plain `dotnet test` produces no archive, no attribution, and no
lost-update detection. Paste this into the target repository's `CLAUDE.md` / `AGENTS.md`:

```markdown
## Running tests

- Run tests through the TestBench MCP tools (`run_tests`, `run_test`) — never plain
  `dotnet test`. TestBench archives the full source tree on every run; a raw `dotnet test`
  archives nothing. CLI fallback:
  `testbench run -p <TestProject> --agent <your-name> --note "<what you changed>"`.
- Don't know the project path? `find_test_projects(<repo root or .sln>)` lists the test
  projects without building anything.
- Always pass `agent` (your name/session) and `note` (one line on what you just changed).
  With several agents in one working tree, this attribution is the only record of whose
  change a run observed.
- Read the `Warnings` field of every `run_tests` response: it reports work that was silently
  overwritten and tests whose output changed while still passing. Both decay fast.
- If work goes missing: `find_last_good_run` → `compare_runs` → `code_at_run` →
  `restore_files_from_run`. The overwritten content is still in the archive.
- Never pass a working tree as a restore/replay target directory. Omit the target to get a
  fresh scratch directory; `overwrite` is only for when the user explicitly asked to replace
  current files.
```

---

## Updating

Re-run `publish.ps1` and replace the contents of `%USERPROFILE%\TestBench\bin` on the target
machine. The history database (`%USERPROFILE%\TestBench\history.db`) is untouched by updates;
schema changes migrate forward automatically on first open.