GoConvey

GoConvey is a Go testing tool that layers BDD-style syntax on top of the standard go test toolchain. Using nested Convey and So blocks, developers describe test scenarios as plain-language stories instead of flat test functions, while GoConvey’s runner translates each nested block into isolated, properly-scoped executions.

Beyond the DSL, GoConvey ships a standalone web server (the goconvey binary) that watches a project’s .go files, reruns affected package tests automatically, and renders colorized, story-formatted results with coverage in the browser — turning go test output into a live dashboard without additional configuration.

What You Get

• Nested Convey/So DSL for writing BDD-style specs that integrate directly with go test
• A large library of built-in assertions (ShouldEqual, ShouldContain, ShouldPanic, etc.) forwarded from the smarty/assertions package
• A self-contained web server (goconvey binary) that watches .go files and reruns affected package tests automatically
• Colorized terminal output and browser-based coverage reporting for every test run

Common Use Cases

• Writing readable BDD-style unit tests for Go packages instead of flat table-driven tests
• Running a live, auto-refreshing test dashboard in the browser during local development
• Generating desktop notifications and coverage reports while iterating on a package
• Retrofitting BDD narrative structure onto existing go test-based test suites

Under The Hood

Architecture GoConvey’s core (convey/context.go, discovery.go) builds a tree of nested execution scopes: each Convey call registers a node, and the runner walks the tree depth-first, re-executing the full path to each leaf so sibling blocks never leak state — the same mechanism Ginkgo-style BDD frameworks use for isolated nested specs. Result formatting is decoupled into a pluggable reporting package (console.go, dot.go, json.go, gotest.go, story.go) selected via build tags, while the separate web/server tree (api, executor, parser, watch, messaging packages) composes an independent HTTP server, file watcher, and concurrent test executor that talks to the browser client over long-polling — a clean split between the assertion DSL and the optional dashboard tool.

Tech Stack The module targets Go 1.21+ and depends on github.com/smarty/assertions for its Should* assertion functions, github.com/jtolds/gls for goroutine-local storage that tracks which nested scope is currently executing without threading context through function signatures, and golang.org/x/tools/go/packages for resolving package names during file watching. The goconvey binary embeds its entire web client (HTML/CSS/JS) via go:embed and serves it with the standard library’s net/http, so the dashboard tool ships as a single static binary with no external runtime dependencies.

Code Quality The project dogfoods its own DSL: isolated_execution_test.go, focused_execution_test.go, reporting_hooks_test.go, and story_conventions_test.go are substantial test files (the largest over 12KB) that exercise the nested-scope runner using GoConvey itself. CI (.travis.yml) runs the suite across Go 1.13–1.16 plus master on both amd64 and ppc64le. There is no linter configuration or static-analysis tooling checked into the repo, and recent commit activity is low relative to the project’s age.

What Makes It Unique Most Go testing helpers are either assertion libraries (like testify) or table-driven test generators; GoConvey instead uses goroutine-local storage to let deeply nested Convey/So blocks execute as isolated subtree runs without any explicit context object passed by the caller, giving BDD-style narrative tests real per-branch isolation. Pairing that DSL with a self-contained, file-watching web dashboard that reruns and visualizes coverage live in the browser is a combination few other Go testing tools offer in one package.