Skip to main content
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 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.
  • 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):
terminal
Output
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:
terminal
Output (trimmed)
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.
internal/pricing/pricing_test.go
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:
terminal
Output (trimmed)
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:
Output
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:
Taskfile.yml
forge.yaml
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:
terminal
Output (trimmed)

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

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/**").
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

How Forge tests work

The two tiers, the embedded Postgres and why child processes break the test cache.

Gate pull requests

Run the whole CI gate locally and in GitHub Actions.

Test against real Postgres

Database tests that stay in the fast tier.

Tracing and test lint rules

Every rule --slow-tests reports.