# Add Test Coverage to CI for an Echo API

Yes. An agent makes an Echo API's Go workflow write a coverage profile across every package, print the per-function table, keep the HTML report and open a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-coverage-to-ci/echo/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Coverage in Go is a flag on `go test`, so the work is in choosing which packages count and where the numbers go. In an API laid out like xesina/golang-echo-realworld-example-app, `go.mod` declares `go 1.18` and depends on `github.com/labstack/echo/v4` `v4.1.16`, `github.com/jinzhu/gorm` `v1.9.8` with its SQLite dialect, `github.com/dgrijalva/jwt-go`, `github.com/swaggo/echo-swagger` and `github.com/stretchr/testify` `v1.4.0`. `.github/workflows/go.yml` is the one workflow: on every push and pull request it checks out with `actions/checkout@v3`, installs Go 1.18 with `actions/setup-go@v3`, runs `go build -v ./...` and `go test -v ./...`, and that is all. The `Makefile` has a `test` target that runs `go test -v -race ./...`, which CI does not use, and `build` runs `go build -race`.

The agent then reads where the tests are. Every `_test.go` file is in `handler/`: `handler_test.go` has a `TestMain` whose `setup()` opens the SQLite file `./../realworld_test.db` through `db.TestDB()`, runs `db.AutoMigrate`, builds the stores, a `Handler` and a `router.New()` Echo instance, and loads two users, two articles and comments as fixtures; `tearDown()` closes the database and `db.DropTestDB()` removes the file. `user_test.go` covers sign-up, login, the current user, profile and follow cases, and `article_test.go` covers list, get, create, update, feed, delete, comments, favourites and tags, each built with `httptest.NewRequest` and `e.NewContext`. The packages `store`, `router`, `utils`, `db`, `model` and `main` have no tests of their own, so a plain `go test -cover` would report a number for `handler` and nothing for the rest, and the whole-project figure would be flattering. Because `mattn/go-sqlite3` needs cgo, the tests only build where a C compiler is present, which the Ubuntu runner has.

The workflow change is one step and three additions. The test step becomes `go test -v -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.out ./...`: `-coverpkg=./...` counts statements in every package, including the ones only reached through the handler tests, so `store` and `utils` show real numbers instead of being absent; `atomic` is the mode `-race` requires. A following step runs `go tool cover -func=coverage.out` so the per-function table and the `total:` line land in the job log and in the step summary through `GITHUB_STEP_SUMMARY`, a third runs `go tool cover -html=coverage.out -o coverage.html` and uploads it with `actions/upload-artifact` so a reviewer can open the coloured source, and a fourth uploads `coverage.out` with `codecov/codecov-action` pinned to its current major, with `fail_ci_if_error` left off so a Codecov outage does not fail the build. Which of the last two the team keeps is a review choice; the pull request explains both. The agent raises `actions/checkout` and `actions/setup-go` to their current majors in the same file, since the old ones warn on every run, and leaves the Go version alone.

To show what the first run will report, the agent installs Go in its sandbox, runs the exact test command from the new workflow, and runs `go tool cover -func=coverage.out` on the result. It pastes the table into the pull request grouped by package, so the reader sees that `handler` is well exercised, that `store` is reached only through those handlers, and that `router/middleware/jwt.go` has branches no test touches, such as the invalid-token and missing-header paths. It writes no new tests; the table is the map for where they belong, and the pull request lists the three functions with the lowest coverage as suggested next targets. `coverage.out` and `coverage.html` are added to `.gitignore` beside the `*.db` pattern already there.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add test coverage reporting to CI for this Echo API. Read go.mod, Makefile, .github/workflows/go.yml, handler/handler_test.go, handler/user_test.go, handler/article_test.go, db/db.go and .gitignore first. Change the test step in go.yml to run go test -v -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.out ./..., add a step that runs go tool cover -func=coverage.out and writes the table to the step summary, a step that renders coverage.html and uploads it as an artifact, and a step that uploads coverage.out with codecov/codecov-action pinned to its current major without failing the build on an upload error. Raise actions/checkout and actions/setup-go to their current majors and keep Go 1.18. Add coverage.out and coverage.html to .gitignore. Install Go in the sandbox, run the new test command and go tool cover -func, and open a pull request that pastes the per-package table, names the three least covered functions, and writes no new tests.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `.github/workflows/go.yml` and `.gitignore` and nothing else. Its description pastes the `go tool cover -func` table from the sandbox grouped by package with the `total:` line, lists the three functions with the lowest coverage and the file each is in, and says which upload step to keep if the team does not use Codecov.

The `Go` workflow runs on the pull request itself, so the first coverage table appears in that run's step summary and `coverage.html` is attached as an artifact; if the repository has a Codecov token or is public, the Codecov comment appears on the pull request too. The run's record on Rush keeps the sandbox test output, so a reviewer can check the table in the description against what the workflow produced.

Before merging, a reviewer decides whether `-race` belongs in CI given it doubles test time, whether to add a coverage threshold later, and whether the Codecov step should stay. The tests, the handlers and the SQLite fixture setup are untouched.

## Run it on every Go repository whose CI runs tests without coverage

An organisation with many Go services starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own workflow, so a service that already writes a profile gets `-coverpkg` and the summary step added, and one with a build matrix gets the upload steps on one leg only.

A team that wants the table in front of every change runs the follow-up as an automation in the Project with a `github` trigger on `pull_request.opened`. The trigger adds the pull request after the prompt, and the run reads the workflow's coverage artifact for that branch and the one for the base branch, and comments with the functions whose coverage dropped, so the number in the summary becomes a sentence a reviewer reads.

## Why run it on Rush?

The flags are easy to get subtly wrong: without `-coverpkg=./...` a package with no test file is simply absent from the total, `-race` without `-covermode=atomic` fails, and `go tool cover -func` on a profile from a different working directory prints paths that match nothing. The agent runs the exact command the workflow will run, in its own sandbox with Go installed and a C compiler for SQLite, and the pull request carries the table that command produced.

Every command stays with the run, from `go test` to the HTML render, so a reviewer sees the numbers before the first workflow run. The same prompt runs across a fleet of Go services at once, each in its own sandbox and with its own pull request, which is how a coverage baseline for twenty repositories gets written in an afternoon.

## Frequently asked questions

### Why -coverpkg=./... instead of plain -cover?

Plain `-cover` measures each package only by its own tests, and this repository's tests all live in `handler/`, so `store`, `utils` and `router` would report nothing. With `-coverpkg=./...` every package's statements are instrumented, so code reached through the handler tests counts and the total reflects the whole module.

### Does the test database need any setup in CI?

No. `db.TestDB()` opens a SQLite file next to the repository root and `TestMain` removes it after the suite. The runner needs a C compiler for `mattn/go-sqlite3`, which `ubuntu-latest` has, and `-race` needs cgo as well, which is on by default there.

### Will the pull request add tests for the uncovered functions?

Not this one. It adds the measurement and names the three least covered functions so the next pull request has a target. Keeping the workflow change separate from new tests makes each easy to review and to revert.

### Do I need a Codecov account?

No. The `go tool cover -func` table in the step summary and the uploaded `coverage.html` work with GitHub alone. The Codecov step is there for a team that wants a trend and a pull request comment; a public repository uploads without a token, a private one needs `CODECOV_TOKEN` as a secret, and either way an upload error does not fail the build.

## More Echo jobs

- [Add Cursor Pagination to an Echo API](https://getrush.ai/run/add-cursor-pagination/echo/)
- [Add Versioned Database Migrations to an Echo App](https://getrush.ai/run/add-database-migrations/echo/)
- [Add Dependabot to an Echo App](https://getrush.ai/run/add-dependabot/echo/)

## The same job on other stacks

- [Add Code Coverage to CI for an Electron App](https://getrush.ai/run/add-coverage-to-ci/electron/)
- [Add Test Coverage to CI for an Elixir App](https://getrush.ai/run/add-coverage-to-ci/elixir/)
- [Add Test Coverage to CI for a Filament App](https://getrush.ai/run/add-coverage-to-ci/filament/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
