# Proof runs

> MergeHarbor writes tests that try to reproduce review findings, runs them in an isolated sandbox, and attaches the evidence to the findings it proves.

A review finding is a claim. A proof run checks it. After a review, MergeHarbor writes small, targeted tests for the findings and for edge cases of the functions the pull request changed, runs them in an isolated sandbox against the pull request, and reports what happened.

- **Proven**: the test fails because the pull request has the problem. MergeHarbor replies under the finding with the failing test, the command and its output, and raises the finding's confidence. Browser tests also attach screenshots and traces.
- **Discarded**: the test itself was wrong or gave different results on two runs. Discarded tests are never posted.
- **Passed**: the behaviour holds. You can see the test in the console and add it to your pull request.

Proof runs work with every review depth. Each run that uses the sandbox costs 2 credits in addition to the review.

## Turn it on

Proof runs are off by default. An administrator turns them on under **Settings → Checks & gates → Proof runs**, where you also choose:

- **When they run**: after every review in scope, or only when someone asks.
- **Rules**: only for pull requests into certain branches, only when certain paths change, and whether to skip drafts.
- **Limits**: tests per run and runs per month for the organization.
- **Replies on findings**: whether proven findings get the evidence as a reply.

Each repository can override these on its page under **Repositories**. Proof runs are included in the Team, Advanced and Enterprise plans.

## Run on request

Comment `@mergeharbor test` on a pull request, or select **Run tests** on the pull request page in the console. The result appears as the **MergeHarbor / proof run** check (GitHub) and on the pull request page, where you can read every test, its output and logs.

## Add a test to your pull request

Any generated test that passed or proved a finding can be added to the pull request from the console with **Add this test to the pull request**. MergeHarbor opens a small pull request into your branch with the test file; it never pushes to your branch directly.

## Tell MergeHarbor how to run your tests

MergeHarbor detects Go, Node.js (Vitest, Jest, Mocha, node:test), Python (pytest), Java and Kotlin (Maven, Gradle), Ruby (RSpec, Minitest), Rust (Cargo) and .NET projects. When your project needs more, add `.mergeharbor/sandbox.yml`:

```yaml
version: 1
language: python
install: pip install -r requirements-dev.txt
setup:
  - make fixtures
test:
  command: pytest -q
  related: pytest -q {dirs}
  run_one: pytest -q {path} -k {name}
services:
  - name: postgres
    image: postgres:17-alpine
    env: { POSTGRES_PASSWORD: test }
    port: 5432
env:
  DATABASE_URL: postgres://postgres:test@postgres:5432/postgres
limits: { memory: 4g, timeout: 15m }
conventions: |
  Tests live next to the code. Use the factories in tests/factories.py.
```

The file is read from the branch the pull request targets, so a pull request cannot change how its own tests are set up.

## What the sandbox allows

- No secrets: the sandbox never receives your code host's credentials or any secret. Use test values in `env`.
- No network, except reaching public package registries while dependencies install. Tests themselves run offline unless your administrator allows otherwise.
- Strict limits on CPU, memory, processes, disk and time. Each run gets a fresh sandbox that is removed afterwards.
- Output is scanned for secrets and redacted before it is stored or shown.

Self-hosted installations run sandboxes on a separate runner service; see the operator guide in `docs/RUNTIME_VALIDATION.md` in the repository.