# Migrate a Go Test Suite From Ginkgo v1 to Ginkgo v2

Yes. An agent moves the imports to ginkgo/v2, rewrites specs that take a Done channel, fixes the CLI flags in CI and shows the same specs pass.

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

## What the agent does

Ginkgo v2 is a new module path, `github.com/onsi/ginkgo/v2`, so the first edit is mechanical: every dot-import of `github.com/onsi/ginkgo` in a `_test.go` file gets the `/v2` suffix. The agent does not stop there, because the import compiles long before the suite is actually migrated. In a library like timehop/apns, `go.mod` requires `github.com/onsi/ginkgo v1.16.5` and `github.com/onsi/gomega v1.27.6`, seven test files import both, and `apns_suite_test.go` is the standard three-line bootstrap with `RegisterFailHandler(Fail)` and `RunSpecs(t, "Apns Suite")`. Before touching anything it runs `go test . -v` and saves the output, including the spec count and the block v1.16.5 already prints under `You're using deprecated Ginkgo functionality`.

That block is the real work list. Eleven specs in `client_test.go`, `conn_test.go` and `feedback_test.go` are written as `It("...", func(d Done) { ... close(d) })`, the v1 way to test asynchronous code with a timeout. v2 removed that. A spec with a `Done` parameter still compiles and still passes, but Ginkgo prints `Your test will run synchronously and the timeout will be ignored` and lists each file and line. So a suite can look migrated while its hang protection is gone. The agent reads each of the eleven bodies and sees that the helper they call, `withMockServer`, already blocks on its own channel until the callback returns. The `Done` parameter was doing nothing the helper did not do, so it removes the parameter and the matching `close(d)` calls, and leaves the helper's own `close(d)` alone because that `d` is a different channel.

Where a spec does need a deadline, it uses the v2 form: a `SpecContext` parameter and a `SpecTimeout` decorator. It then looks for the other v1 features that v2 dropped: `Measure` blocks, custom reporters passed to `RunSpecsWithDefaultAndCustomReporters`, and `CurrentGinkgoTestDescription`. This suite uses none of them, and the agent says so with the search it ran.

The CLI changes too. `.travis.yml` installs `github.com/onsi/ginkgo/ginkgo` and runs `ginkgo -r --skipMeasurements --cover --trace`, and the README tells contributors to `go get github.com/onsi/ginkgo/ginkgo` and run `ginkgo -randomizeAllSpecs`. The v2 CLI lives at `github.com/onsi/ginkgo/v2/ginkgo` and refuses the first command with `flag provided but not defined: -skipMeasurements`. The agent updates the install path, drops that flag, writes the randomize flag in its v2 spelling, `--randomize-all`, and runs the new command line to show it works. It also decides which v2 release to require, and that choice has a cost it reports: `go mod tidy` alone settles on v2.9.2, the release gomega v1.27.6 already depends on, and leaves `go 1.20` in place, while `go get github.com/onsi/ginkgo/v2@latest` also raises gomega and the `go` directive.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this Go repository's tests from Ginkgo v1 (github.com/onsi/ginkgo) to Ginkgo v2 (github.com/onsi/ginkgo/v2). First run the test suite as it is with go test -v, save the output, and note the number of specs and every line under any deprecation notice Ginkgo prints. Change every import of github.com/onsi/ginkgo and its subpackages (extensions/table, config, reporters, types) to the v2 path; DescribeTable and Entry now come from the main package. Then remove v1 features that v2 dropped, one kind at a time: specs or setup nodes that take a Done channel (if the body already blocks until the work finishes, drop the parameter and its close call; if it needs a deadline, take a SpecContext and add SpecTimeout or NodeTimeout; never leave a Done parameter in place), Measure blocks, custom reporters and RunSpecsWithDefaultAndCustomReporters (use ReportAfterSuite or the --junit-report flag), CurrentGinkgoTestDescription (use CurrentSpecReport), and GinkgoParallelNode (use GinkgoParallelProcess). For each kind, print the search you ran and the count before and after. Update the ginkgo CLI everywhere it is installed or called: Makefile, CI workflows, scripts and README. Use the v2 install path and replace removed or renamed flags; run each updated command line once to prove the CLI accepts it. Choose the Ginkgo v2 version deliberately: compare what go mod tidy picks on its own with what go get @latest picks, list every other line of go.mod each choice changes including the go directive and gomega, and take the smaller change unless a feature you used needs the newer release. Run go mod tidy and confirm github.com/onsi/ginkgo without /v2 is gone from go.mod. Run the suite again with -v and compare: the same number of specs must run and pass, and no deprecation notice may remain. Do not set ACK_GINKGO_DEPRECATIONS to hide one. Open a pull request with the before and after output.",
  "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

A pull request that changes the import line in each test file, removes the `Done` parameter from the eleven async specs, and edits `go.mod`, `go.sum`, `.travis.yml` and the README's test instructions. The description puts the two `go test -v` summaries next to each other so the reviewer can compare the `Ran N of N Specs` lines, and it shows that the deprecation block is absent from the second one. The count before and after for each removed feature is in a short table.

The part to read closely is the async specs. For each one the reviewer checks that the body really is synchronous once `Done` is gone, which here means it sits inside a `withMockServer` or `withMockServerAsync` callback that the helper waits for. A spec that is rewritten with `SpecContext` and `SpecTimeout` instead gets its deadline named in the diff, where v1 hid a default timeout behind the channel.

The `go.mod` section of the description names the version it chose and what the other choice would have moved. The CI file in this repository is a Travis configuration pinned to Go 1.3, older than the `go` directive in `go.mod`; the agent updates the commands in it and reports the mismatch, without inventing a replacement workflow nobody asked for.

## Run it on every repository still on Ginkgo v1

Ginkgo suites spread through an organisation by copy, so the same v1 patterns appear in many repositories. From a script, list the repositories whose `go.mod` has a `github.com/onsi/ginkgo v1` line and send this body to `POST /o/{org}/sessions` for each, with the repository in `resources` and a `request_id` that is a UUID v5 of its full name. A second pass of the script then returns the sessions the first pass started.

Runs beyond the key's `max_concurrent` wait as `queued` and start as slots free. With a `webhook_url` set on the key, each finished run posts `run.completed` to your endpoint, and the session read gives you the pull request to review.

## Why run it on Rush?

This migration has a false finish: the suite compiles and passes on v2 while eleven specs have quietly lost their timeouts. Catching that depends on reading test output, not on an exit code. The agent's sandbox keeps the verbose output from before and after, and the session's transcript holds both, so the claim that no deprecation notice remains can be checked against the text Ginkgo printed.

It also needs commands a reviewer rarely reruns by hand: the old CLI line against the new CLI to see it refused, the new line to see it accepted, and two different dependency resolutions to compare their effect on `go.mod`. Each runs in a clean machine with no globally installed `ginkgo` binary to mask a wrong install path. Twenty repositories can go through the same steps, each in its own sandbox.

## Frequently asked questions

### What replaces the Done channel in Ginkgo v2?

Nothing one-for-one. v2 runs every spec synchronously, so a body that already waits for its goroutines needs no channel at all. For a deadline, declare the spec as `func(ctx SpecContext)` and add `SpecTimeout(...)`; Ginkgo cancels the context when the time is up, and code that respects the context stops.

### My suite passes on v2 but prints a deprecation warning. Is that a problem?

Usually yes. The notice about `Done` says the timeout is ignored, which means a spec that hangs now hangs until `go test` itself times out. Setting `ACK_GINKGO_DEPRECATIONS` silences the message and keeps the behaviour, so the prompt forbids it.

### Do I have to upgrade Gomega as well?

Not necessarily. Recent Gomega v1 releases work with Ginkgo v2 and some already depend on it, in which case `go mod tidy` picks a compatible v2 without moving Gomega. Asking for the latest Ginkgo can raise Gomega and the `go` directive with it; the agent shows both outcomes and takes the smaller one by default.

### Why does the ginkgo command fail with "flag provided but not defined" after the upgrade?

The v2 CLI removed some v1 flags and renamed others to dashed lower case. `--skipMeasurements` is gone along with `Measure`. Install the CLI from `github.com/onsi/ginkgo/v2/ginkgo` at the same version as the library and update the flags in CI and in any Makefile.

## More jobs like this: Upgrade dependencies weekly

- [Replace go-bindata With go:embed in a Go Web Server](https://getrush.ai/run/migrate-go-bindata-to-embed/go-bindata/)
- [Replace mitchellh/go-homedir With os.UserHomeDir in a Go CLI](https://getrush.ai/run/migrate-go-homedir-to-os-userhomedir/go-homedir/)
- [Replace hashicorp/go-multierror With errors.Join in a Go Project](https://getrush.ai/run/migrate-go-multierror-to-errors-join/go-multierror/)
- [Migrate From go-redis v8 to v9 (github.com/redis/go-redis/v9)](https://getrush.ai/run/migrate-go-redis-v8-to-v9/go-redis/)
- [Replace mattn/go-sqlite3 With modernc.org/sqlite for a cgo-Free Go Build](https://getrush.ai/run/migrate-go-sqlite3-to-modernc-sqlite/go-sqlite3/)
- [Migrate From gopkg.in/yaml.v2 to yaml.v3 in a Go Project](https://getrush.ai/run/migrate-go-yaml-v2-to-v3/go-yaml/)

## 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/)
