> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Keep your test suite fast: mark slow tests and enforce budgets

> Find the Go tests that slow every edit, mark them with testkit.Slow so they leave the -short tier, and fail CI when a new slow test arrives unmarked.

By the end of this guide, the tests you run on every edit (`go test -short`, or `task test:short`) stay under a time budget, the slow ones still run in the full tier, and your CI gate fails when someone adds a slow test without marking it. Two checks find the offenders: one reads a timed test run, the other reads your source. [How Forge tests work](https://docs.reliantlabs.io/deep-dives/how-forge-tests-work.md#marking-the-slow-tests) explains why there are two and why a child process breaks Go's test cache.

## Before you begin

* A Forge Go project in a git repository, such as the one from [Build a Go and React app](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md).
* Forge v1.6.1 or later in the project (`reliant forge --version`).

The examples use a small `internal/pricing` package with two problem tests: `TestRoundCentsExhaustive` loops over ten billion prices, and `TestPriceFixturesTracked` runs `git ls-files`.

**1. Time the fast tier**

Feed a `-short` run to `forge ci test-budget`. It reports every top-level test that took longer than `--budget` (default `2s`):

```bash terminal theme={null}
go test -short -json ./... | reliant forge ci test-budget
```

```text Output theme={null}
test budget 2s: 3 test(s) ran, 1 over budget
  ✗ TestRoundCentsExhaustive                             2.99s  internal/pricing/pricing_test.go:16
forge ci test-budget: 1 test(s) not marked slow took longer than 2s. Fix: make each one fast, or mark it slow so it runs in the full tier: testkit.Slow(t, "<what makes it slow>") (forge/pkg/testkit), or `if testing.Short() { t.Skip("<why>") }`.
```

A failing or unbuildable package also fails the command, so a red run piped through it never reports green.

**2. Find slow work in the source**

A test can be quick today and still break the cache: the git test above takes milliseconds, so the timer misses it. `--slow-tests` flags a test that execs `go`, `forge`, `kcl`, `node`, `npm`, `git` or `docker`, drives containers, or dials an external host:

```bash terminal theme={null}
reliant forge lint --slow-tests
```

```text Output (trimmed) theme={null}
❌ slow-tests — 1 error
   ✗ internal/pricing/pricing_test.go:25 [forge-slow-test-unmarked] TestPriceFixturesTracked is not marked slow but execs `git` at pricing_test.go:26; mark it slow so it leaves the fast tier
```

The lint follows calls, so a helper that execs is attributed to the test that calls it. It cannot see a CPU-bound loop, which is why you run both checks.

**3. Mark the slow tests**

Call `testkit.Slow` first in each one. The reason becomes the skip message. `testkit.Inputs` names the files a test reads through a child process; the globs must be string literals.

```go internal/pricing/pricing_test.go theme={null}
import "github.com/reliant-labs/forge/pkg/testkit"

func TestRoundCentsExhaustive(t *testing.T) {
	testkit.Slow(t, "checks ten billion prices")
	// ...
}

func TestPriceFixturesTracked(t *testing.T) {
	testkit.Slow(t, "execs git over the checkout", testkit.Inputs("internal/pricing/testdata/**"))
	out, err := exec.Command("git", "ls-files", "testdata").Output()
	// ...
}
```

If a test is slow because it waits on something it does not need, such as a production timeout, shorten the wait in the test instead of marking it.

**4. Verify both tiers**

Under `-short` the marked tests skip and say where they run:

```bash terminal theme={null}
go test -short -v ./internal/pricing/
```

```text Output (trimmed) theme={null}
--- PASS: TestRoundCents (0.00s)
    pricing_test.go:19: slow test, skipped under -short: checks ten billion prices; runs in the full tier (go test without -short, task test)
--- SKIP: TestRoundCentsExhaustive (0.00s)
    pricing_test.go:29: slow test, skipped under -short: execs git over the checkout; runs in the full tier (go test without -short, task test)
--- SKIP: TestPriceFixturesTracked (0.00s)
ok  	example.com/shop/internal/pricing	0.009s
```

Both checks now pass (`test budget 2s: 1 test(s) ran, 0 over budget` and `✓ slow-tests`). Without `-short`, as `task test` and the generated CI `test` job run it, all three tests run:

```text Output theme={null}
--- PASS: TestRoundCents (0.00s)
--- PASS: TestRoundCentsExhaustive (2.99s)
--- PASS: TestPriceFixturesTracked (0.00s)
ok  	example.com/shop/internal/pricing	3.007s
```

**5. Enforce the budget in the gate**

Neither check is a row of `task ci` until you add it. Add a task that runs both with the project's pinned forge, then declare it as an extra check:

```yaml Taskfile.yml theme={null}
  test:budget:
    desc: Fail on a slow test nobody marked slow (source check, then a timed -short run)
    cmds:
      - "{{.FORGE}} lint --slow-tests"
      - "go test -short -json ./... | {{.FORGE}} ci test-budget"
```

```yaml forge.yaml theme={null}
ci:
  gate:
    extra_checks:
      - name: test-budget
        command: [task, test:budget]
        heavy: true
```

The row runs in the `checks` lane of `task ci` and of the generated `ci.yml`. With the mark removed from the loop test again:

```bash terminal theme={null}
CI_ONLY=test-budget reliant forge ci gate checks
```

```text Output (trimmed) theme={null}
✗ test-budget  FAIL 7.3s — exit status 201 (log: tmp/ci/checks/test-budget.log)
    | test budget 2s: 12 test(s) ran, 1 over budget
    |   ✗ TestRoundCentsExhaustive                             3.18s  internal/pricing/pricing_test.go:18

CI gate summary (checks)
  CHECK        RESULT      TIME  NOTE
  test-budget  FAIL        7.3s  exit status 201; log: tmp/ci/checks/test-budget.log
```

## What this does not do

* **It does not mark tests for you.** Both checks report; you decide whether to speed a test up or mark it.
* **It times top-level tests only.** A table test whose cases add up past the budget is reported as one test, because that is where the mark goes.
* **It cannot see the flags a run was made with.** Feed `test-budget` a `-short` run. A marked test that still takes too long is reported as `MARKED`: either its bypass leaves slow work behind, or the run was made without `-short`.
* **It is not a hard gate on day one unless you want it.** In a large suite, start with `reliant forge ci test-budget --warn-only`, which reports overruns without failing, and drop the flag once the list is empty.

## Troubleshooting

> [accordion] \[forge-slow-test-inputs]
>
> A `testkit.Inputs` argument is not a string literal, such as a variable or a `filepath.Join` call. The lint reads the globs from source without running the test, so write each glob as a literal: `testkit.Inputs("deploy/kcl/**")`.

> [accordion] A test is listed as MARKED
>
> The test calls `testkit.Slow` or checks `testing.Short`, yet it ran and went over budget. Check that the run used `-short`, and that the mark comes before the slow work rather than after it.

## Next steps

> [card] [How Forge tests work](https://docs.reliantlabs.io/deep-dives/how-forge-tests-work.md)
>
> The two tiers, the embedded Postgres and why child processes break the test cache.

> [card] [Gate pull requests](https://docs.reliantlabs.io/guides/forge/gate-prs-forge-lint-tests.md)
>
> Run the whole CI gate locally and in GitHub Actions.

> [card] [Test against real Postgres](https://docs.reliantlabs.io/guides/forge/test-go-api-real-postgres.md)
>
> Database tests that stay in the fast tier.

> [card] [Tracing and test lint rules](https://docs.reliantlabs.io/forge/linting/rules-tracing-and-tests.md#tests)
>
> Every rule `--slow-tests` reports.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.