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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
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 (go-bindata)
- Replace mitchellh/go-homedir With os.UserHomeDir in a Go CLI (go-homedir)
- Replace hashicorp/go-multierror With errors.Join in a Go Project (go-multierror)
- Migrate From go-redis v8 to v9 (github.com/redis/go-redis/v9) (go-redis)
- Replace mattn/go-sqlite3 With modernc.org/sqlite for a cgo-Free Go Build (go-sqlite3)
- Migrate From gopkg.in/yaml.v2 to yaml.v3 in a Go Project (go-yaml)