Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
BDD Testing Framework for Go
Go
tree: 884dab811f

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config
ginkgo
remote
reporters
stenographer
thirdparty/gomocktestreporter
types
.gitignore
.travis.yml
MIT.LICENSE
README.md
benchmarker.go
benchmarker_test.go
container_node.go
container_node_test.go
enums_and_types.go
example.go
example_collection.go
example_collection_test.go
example_test.go
ginkgo.go
ginkgo_suite_test.go
ginkgo_testing_t_proxy.go
helpers.go
helpers_test.go
measure_node.go
measure_node_test.go
runnable_node.go
runnable_node_test.go
suite.go
suite_test.go

README.md

Ginkgo: A Golang BDD Testing Framework

Build Status

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

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
  • 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.

  • 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
    • ginkgo -cover will run your tests using Golang'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
    • ginkgo -watch watches packages for changes, then reruns tests

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

  • A modular architecture that lets you easily:

Gomega: Ginkgo's Preferred Matcher Library

Learn more about Gomega here

Set Me Up!

You'll need Golang v1.2+ (Ubuntu users: you probably have Golang v1.0 -- you'll need to upgrade!)

go get github.com/onsi/ginkgo/ginkgo  # installs the ginkgo CLI
go get github.com/onsi/gomega         # 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 Golang gives you out of the box

Testing is a first class citizen in Golang, 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 Golang'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 Golang. Here are a few:

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

Go explore!

License

Ginkgo is MIT-Licensed

ginkgo -watch uses fsnotify which is embedded in the source to simplify distribution. fsnotify has a BSD-style license. This dependency will be removed when fsnotify is added to Golang's standard library in v1.3

Something went wrong with that request. Please try again.