# GoConvey — Go Testing with Browser UI

> A BDD-style testing framework for Go that includes a live-reloading browser interface. Write expressive specs with nested Convey blocks and watch results update in real time.

## Install

Save as a script file and run:

# GoConvey — Go Testing with Browser UI

## Quick Use
```bash
go install github.com/smartystreets/goconvey@latest
cd myproject
goconvey   # starts web UI on http://localhost:8080
```
```go
func TestAdd(t *testing.T) {
    Convey("Given two numbers", t, func() {
        a, b := 2, 3
        Convey("When added", func() {
            result := a + b
            Convey("The sum should be correct", func() {
                So(result, ShouldEqual, 5)
            })
        })
    })
}
```

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

---
Source: https://tokrepo.com/en/workflows/asset-1289b187
Author: Script Depot