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: 8ecc0b5f18

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
cleanup
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
ginkgo_writer.go
ginkgo_writer_test.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!

To discuss Ginkgo and get updates, join the google group.

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.