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

# Add tests to a package

> Raise test coverage for one package or endpoint, with gates that prove the new tests run and pass.

You want more tests for one part of your code, such as the `notes` package in `acme/notes-api`. You give Bellows a prompt that names the package and the cases. The agent writes the tests, runs them while it works, and the gates confirm they pass before a pull request is published.

## Before you start

* Your repo has a `.bellows.yaml` with an `image` and a test gate. See [Configure your repo](https://docs.bellows.cloud/guides/configure-repo.md).
* You know how [gates](https://docs.bellows.cloud/guides/gates.md) run, including `on_demand` and `filter`.
* If the integration tests need Postgres or Redis, declare it as a [service](https://docs.bellows.cloud/guides/services.md).
* You can create tasks in the app, the [CLI](https://docs.bellows.cloud/cli/commands.md) or the [MCP server](https://docs.bellows.cloud/mcp/tools.md). See [Run tasks](https://docs.bellows.cloud/guides/run-tasks.md).

## Steps

**1. Add gates that verify the work**

Keep the full `test` gate. Add an `on_demand` gate with `filter: true`, so the agent can run just the tests it is writing in seconds instead of the whole suite.

```yaml .bellows.yaml theme={null}
environment:
    image: golang:1.25
    cache:
        - GOCACHE
        - GOMODCACHE
    setup: "go mod download"
    gates:
        - name: build
          command: "go build ./..."
          timeout: 5
        - name: test
          command: "go test -race -count=1 ./..."
          timeout: 10
        - name: test-filter
          command: 'go test -race -count=1 -run "$GATE_FILTER" ./...'
          on_demand: true
          filter: true
```

Commit this to the default branch first. Bellows reads the file from the base branch, not from the agent's work.

**2. Optionally fail under a coverage threshold**

A gate is any shell command, so a coverage check is a plain script. This one fails if the `notes` package is under 80 percent.

```yaml .bellows.yaml (excerpt) theme={null}
        - name: coverage
          command: 'go test -count=1 -coverprofile=c.out ./internal/notes/ && go tool cover -func=c.out | awk "/^total:/ { sub(/%/, \"\", \$3); exit (\$3 < 80) }"'
          timeout: 10
```

That quoting is hard to read. If you want a threshold that is easy to change, put it in a script in your repo and set `command: "sh scripts/check-coverage.sh"`. The gate writes `c.out` into the tree, so add it to `.gitignore`.

**3. Write a prompt that names the package and the cases**

Click **New task**, pick `acme/notes-api` and an [executor](https://docs.bellows.cloud/guides/executors.md), and describe the work.

```text Prompt theme={null}
Add unit tests for the notes package in internal/notes.

Cover these cases:
- Create: empty title is rejected, title over 200 chars is rejected,
  duplicate title for the same user is rejected.
- Update: unknown id returns ErrNotFound, a stale version returns ErrConflict.
- Delete: deleting twice is idempotent.
- List: pagination returns the right page and an empty page past the end.

Use table-driven tests and the existing fakes in internal/notes/testutil.
Do not change production code. If you find a bug, leave a failing test
out and describe the bug in the pull request instead.

Run the test-filter gate while you iterate, then run the full test gate
before you finish.
```

**4. Review the result**

Open the task. The **Verification** panel shows each gate. When it is green, review the pull request.

## What you get

* A pull request that adds only test files, when you said not to touch production code.
* Gate results in the task's **Verification** panel: `build`, `test` and, if you added it, `coverage`.
* A summary of what was covered and what was skipped, in the pull request and the final message.

> [!NOTE]
>
> If a gate keeps failing, Bellows runs repair rounds and then ships a draft pull request. To block publishing until gates pass, set `policy: gates: required`. See [Policy and reviewers](https://docs.bellows.cloud/guides/policy-and-reviewers.md).

## Tips

* One package or endpoint per task. A narrow task finishes faster and gives a pull request you can read.
* Say "do not change production code" when that is what you want. Otherwise the agent may refactor to make code testable.
* Name the cases. "Add tests" gets happy paths. A list of edge cases gets edge cases.
* Read the test names in the diff first. They show quickly whether the agent understood the cases.
* Follow up for gaps, for example "add a test for a nil context in Create". The agent continues in the same checkout. See [Task lifecycle](https://docs.bellows.cloud/guides/task-lifecycle.md).
* Keep the filtered gate at 10 minutes or less, or the agent cannot run it while it works.

## Variations

* **Postgres-backed tests.** Add a `db` service and point your test at `localhost`. See [Services](https://docs.bellows.cloud/guides/services.md).
* **Node project.** Use `npx vitest run $GATE_FILTER` for the filtered gate and `npm_config_cache` in `cache`.


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