Skip to content
BDD Testing Framework for Go
Branch: master
Clone or download
Latest commit eea6ad0 Mar 8, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
config v1.8.0 Mar 8, 2019
extensions/table We no longer pass untyped nils to the reflect::Value.Call Jan 27, 2016
ginkgo allow config of the vet flag for `go test` (#562) Mar 7, 2019
integration Ensure generated test file names are underscored Dec 5, 2018
internal Optimize focus to avoid allocations Jan 30, 2019
reporters Correctly round suite time in junit reporter Sep 17, 2018
types Add JustAfterEach (#484) Nov 5, 2018
.gitignore Add JustAfterEach (#484) Nov 5, 2018
.travis.yml v1.8.0 Mar 8, 2019 docs: fix for contributing instructions Jul 17, 2018
LICENSE Generalized LICENSE filename Sep 8, 2014 Bring the changelog up to date (#470) May 10, 2018
ginkgo_dsl.go chore(godoc): fixes typos in Measurement funcs Feb 26, 2019

Ginkgo: A Go BDD Testing Framework

Build Status

Jump to the docs to learn more. To start rolling your Ginkgo tests now keep reading!

If you have a question, comment, bug report, feature request, etc. please open a GitHub issue.

Feature List

  • Ginkgo uses Go's testing package and can live alongside your existing testing tests. It's easy to bootstrap and start writing your first tests

  • Structure your BDD-style tests expressively:

  • A comprehensive test runner that lets you:

    • Mark specs as pending
    • Focus individual specs, and groups of specs, either programmatically or on the command line
    • Run your tests in random order, and then reuse random seeds to replicate the same order.
    • Break up your test suite into parallel processes for straightforward test parallelization
  • ginkgo: a command line interface with plenty of handy command line arguments for running your tests and generating test files. Here are a few choice examples:

    • ginkgo -nodes=N runs your tests in N parallel processes and print out coherent output in realtime
    • ginkgo -cover runs your tests using Go's code coverage tool
    • ginkgo convert converts an XUnit-style testing package to a Ginkgo-style package
    • ginkgo -focus="REGEXP" and ginkgo -skip="REGEXP" allow you to specify a subset of tests to run via regular expression
    • ginkgo -r runs all tests suites under the current directory
    • ginkgo -v prints out identifying information for each tests just before it runs

    And much more: run ginkgo help for details!

    The ginkgo CLI is convenient, but purely optional -- Ginkgo works just fine with go test

  • ginkgo watch watches packages and their dependencies for changes, then reruns tests. Run tests immediately as you develop!

  • Built-in support for testing asynchronicity

  • Built-in support for benchmarking your code. Control the number of benchmark samples as you gather runtimes and other, arbitrary, bits of numerical information about your code.

  • Completions for Sublime Text: just use Package Control to install Ginkgo Completions.

  • Completions for VSCode: just use VSCode's extension installer to install vscode-ginkgo.

  • Straightforward support for third-party testing libraries such as Gomock and Testify. Check out the docs for details.

  • A modular architecture that lets you easily:

Gomega: Ginkgo's Preferred Matcher Library

Ginkgo is best paired with Gomega. Learn more about Gomega here

Agouti: A Go Acceptance Testing Framework

Agouti allows you run WebDriver integration tests. Learn more about Agouti here

Set Me Up!

You'll need the Go command-line tools. Ginkgo is tested with Go 1.6+, but preferably you should get the latest. Follow the installation instructions if you don't have it installed.

go get -u  # installs the ginkgo CLI
go get -u     # fetches the matcher library

cd path/to/package/you/want/to/test

ginkgo bootstrap # set up a new ginkgo suite
ginkgo generate  # will create a sample test file.  edit this file and add your tests then...

go test # to run your tests

ginkgo  # also runs your tests

I'm new to Go: What are my testing options?

Of course, I heartily recommend Ginkgo and Gomega. Both packages are seeing heavy, daily, production use on a number of projects and boast a mature and comprehensive feature-set.

With that said, it's great to know what your options are :)

What Go gives you out of the box

Testing is a first class citizen in Go, however Go's built-in testing primitives are somewhat limited: The testing package provides basic XUnit style tests and no assertion library.

Matcher libraries for Go's XUnit style tests

A number of matcher libraries have been written to augment Go's built-in XUnit style tests. Here are two that have gained traction:

You can also use Ginkgo's matcher library Gomega in XUnit style tests

BDD style testing frameworks

There are a handful of BDD-style testing frameworks written for Go. Here are a few:

Finally, @shageman has put together a comprehensive comparison of Go testing libraries.

Go explore!


Ginkgo is MIT-Licensed



You can’t perform that action at this time.