GoConvey — Go Testing with Browser UI

Introduction

GoConvey brings BDD-style test organization to Go with nested Convey blocks and a rich set of built-in assertions. Its standout feature is a web server that watches your source files, re-runs tests on save, and displays results in a browser with color-coded pass/fail indicators and desktop notifications.

What GoConvey Does

• Organizes tests with nested Convey blocks for context-driven specs
• Provides 30+ built-in So assertions like ShouldEqual, ShouldContainSubstring, ShouldBeNil
• Runs a web UI that live-reloads test results on file changes
• Sends desktop notifications on test pass/fail transitions
• Integrates with standard go test without requiring a custom runner

Architecture Overview

GoConvey's DSL registers closures in a tree rooted at the top-level Convey call. The runner executes each path from root to leaf, re-running parent closures to isolate state. The web server watches the filesystem with fsnotify, triggers go test -json on changes, parses the JSON output, and pushes results to the browser over a WebSocket connection.

Setup & Configuration

• Install the CLI with go install github.com/smartystreets/goconvey@latest
• Run goconvey in your project root to start the web UI
• Access the dashboard at http://localhost:8080
• Change the port with goconvey -port=9090
• Use goconvey -depth=2 to limit recursive package scanning depth

Key Features

• Live-reloading browser UI with per-package pass/fail breakdown
• Desktop notifications via the Web Notifications API
• Built-in assertions cover equality, containment, nil checks, panics, and more
• Custom assertions can be written as functions matching the assertion signature
• Works alongside standard Go tests in the same file

Comparison with Similar Tools

• Ginkgo — richer lifecycle hooks and parallel execution; no built-in browser UI
• Testify — assertion-focused library without BDD nesting or web dashboard
• testing (stdlib) — zero dependencies but no BDD structure or visual feedback
• GoBDD — similar BDD approach with Gherkin-style Given/When/Then syntax

FAQ

Q: Can I use GoConvey without the web UI? A: Yes. GoConvey specs run with plain go test. The web UI is an optional tool for development-time feedback.

Q: Does GoConvey support parallel tests? A: Convey blocks within a single TestX function run sequentially. You can parallelize at the package level with go test -parallel.

Q: How do I write a custom assertion? A: Write a function with the signature func(actual interface{}, expected ...interface{}) string that returns an empty string on success or an error message on failure.

Q: Is GoConvey compatible with Testify? A: You can use both in the same project. Inside a Convey block, use So assertions for GoConvey-native reporting, or call Testify assertions with the testing.T from the outer function.

Sources

• https://github.com/smartystreets/goconvey
• http://goconvey.co/