README

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

    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.

  • 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 Golang Acceptance Testing Framework

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

Set Me Up!

You'll need Golang v1.3+ (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

Documentation

Overview

    Ginkgo is a BDD-style testing framework for Golang

    The godoc documentation describes Ginkgo's API. More comprehensive documentation (with examples!) is available at http://onsi.github.io/ginkgo/

    Ginkgo's preferred matcher library is [Gomega](http://github.com/onsi/gomega)

    Ginkgo on Github: http://github.com/onsi/ginkgo

    Ginkgo is MIT-Licensed

    Index

    Constants

    View Source
    const GINKGO_PANIC = `` /* 332-byte string literal not displayed */
    
    View Source
    const GINKGO_VERSION = config.VERSION

    Variables

    View Source
    var GinkgoWriter io.Writer

      GinkgoWriter implements an io.Writer When running in verbose mode any writes to GinkgoWriter will be immediately printed to stdout. Otherwise, GinkgoWriter will buffer any writes produced during the current test and flush them to screen only if the current test fails.

      Functions

      func AfterEach

      func AfterEach(body interface{}, timeout ...float64) bool

        AfterEach blocks are run after It blocks. When multiple AfterEach blocks are defined in nested Describe and Context blocks the innermost AfterEach blocks are run first.

        Like It blocks, AfterEach blocks can be made asynchronous by providing a body function that accepts a Done channel

        func AfterSuite

        func AfterSuite(body interface{}, timeout ...float64) bool

        AfterSuite blocks are *always* run after all the specs regardless of whether specs have passed or failed. Moreover, if Ginkgo receives an interrupt signal (^C) it will attempt to run the AfterSuite before exiting.

        When running in parallel, each parallel node process will call AfterSuite.

        AfterSuite blocks can be made asynchronous by providing a body function that accepts a Done channel

        You may only register *one* AfterSuite handler per test suite. You typically do so in your bootstrap file at the top level.

        func BeforeEach

        func BeforeEach(body interface{}, timeout ...float64) bool

          BeforeEach blocks are run before It blocks. When multiple BeforeEach blocks are defined in nested Describe and Context blocks the outermost BeforeEach blocks are run first.

          Like It blocks, BeforeEach blocks can be made asynchronous by providing a body function that accepts a Done channel

          func BeforeSuite

          func BeforeSuite(body interface{}, timeout ...float64) bool

          BeforeSuite blocks are run just once before any specs are run. When running in parallel, each parallel node process will call BeforeSuite.

          BeforeSuite blocks can be made asynchronous by providing a body function that accepts a Done channel

          You may only register *one* BeforeSuite handler per test suite. You typically do so in your bootstrap file at the top level.

          func By

          func By(text string, callbacks ...func())

            By allows you to better document large Its.

            Generally you should try to keep your Its short and to the point. This is not always possible, however, especially in the context of integration tests that capture a particular workflow.

            By allows you to document such flows. By must be called within a runnable node (It, BeforeEach, Measure, etc...) By will simply log the passed in text to the GinkgoWriter. If By is handed a function it will immediately run the function.

            func Context

            func Context(text string, body func()) bool

              Context blocks allow you to organize your specs. A Context block can contain any number of BeforeEach, AfterEach, JustBeforeEach, It, and Measurement blocks.

              In addition you can nest Describe and Context blocks. Describe and Context blocks are functionally equivalent. The difference is purely semantic -- you typical Describe the behavior of an object or method and, within that Describe, outline a number of Contexts.

              func Describe

              func Describe(text string, body func()) bool

                Describe blocks allow you to organize your specs. A Describe block can contain any number of BeforeEach, AfterEach, JustBeforeEach, It, and Measurement blocks.

                In addition you can nest Describe and Context blocks. Describe and Context blocks are functionally equivalent. The difference is purely semantic -- you typical Describe the behavior of an object or method and, within that Describe, outline a number of Contexts.

                func FContext

                func FContext(text string, body func()) bool

                  You can focus the tests within a describe block using FContext

                  func FDescribe

                  func FDescribe(text string, body func()) bool

                    You can focus the tests within a describe block using FDescribe

                    func FIt

                    func FIt(text string, body interface{}, timeout ...float64) bool

                      You can focus individual Its using FIt

                      func FMeasure

                      func FMeasure(text string, body interface{}, samples int) bool

                        You can focus individual Measures using FMeasure

                        func Fail

                        func Fail(message string, callerSkip ...int)

                          Fail notifies Ginkgo that the current spec has failed. (Gomega will call Fail for you automatically when an assertion fails.)

                          func GinkgoParallelNode

                          func GinkgoParallelNode() int

                            GinkgoParallelNode returns the parallel node number for the current ginkgo process The node number is 1-indexed

                            func GinkgoRecover

                            func GinkgoRecover()

                              GinkgoRecover should be deferred at the top of any spawned goroutine that (may) call `Fail` Since Gomega assertions call fail, you should throw a `defer GinkgoRecover()` at the top of any goroutine that calls out to Gomega

                              Here's why: Ginkgo's `Fail` method records the failure and then panics to prevent further assertions from running. This panic must be recovered. Ginkgo does this for you if the panic originates in a Ginkgo node (an It, BeforeEach, etc...)

                              Unfortunately, if a panic originates on a goroutine *launched* from one of these nodes there's no way for Ginkgo to rescue the panic. To do this, you must remember to `defer GinkgoRecover()` at the top of such a goroutine.

                              func It

                              func It(text string, body interface{}, timeout ...float64) bool

                                It blocks contain your test code and assertions. You cannot nest any other Ginkgo blocks within an It block.

                                Ginkgo will normally run It blocks synchronously. To perform asynchronous tests, pass a function that accepts a Done channel. When you do this, you can also provide an optional timeout.

                                func JustBeforeEach

                                func JustBeforeEach(body interface{}, timeout ...float64) bool

                                  JustBeforeEach blocks are run before It blocks but *after* all BeforeEach blocks. For more details, read the [documentation](http://onsi.github.io/ginkgo/#separating_creation_and_configuration_)

                                  Like It blocks, BeforeEach blocks can be made asynchronous by providing a body function that accepts a Done channel

                                  func Measure

                                  func Measure(text string, body interface{}, samples int) bool

                                    Measure blocks run the passed in body function repeatedly (determined by the samples argument) and accumulate metrics provided to the Benchmarker by the body function.

                                    The body function must have the signature:

                                    func(b Benchmarker)
                                    

                                    func PContext

                                    func PContext(text string, body func()) bool

                                      You can mark the tests within a describe block as pending using PContext

                                      func PDescribe

                                      func PDescribe(text string, body func()) bool

                                        You can mark the tests within a describe block as pending using PDescribe

                                        func PIt

                                        func PIt(text string, _ ...interface{}) bool

                                          You can mark Its as pending using PIt

                                          func PMeasure

                                          func PMeasure(text string, _ ...interface{}) bool

                                            You can mark Maeasurements as pending using PMeasure

                                            func RunSpecs

                                            func RunSpecs(t GinkgoTestingT, description string) bool

                                              RunSpecs is the entry point for the Ginkgo test runner. You must call this within a Golang testing TestX(t *testing.T) function.

                                              To bootstrap a test suite you can use the Ginkgo CLI:

                                              ginkgo bootstrap
                                              

                                              func RunSpecsWithCustomReporters

                                              func RunSpecsWithCustomReporters(t GinkgoTestingT, description string, specReporters []Reporter) bool

                                                To run your tests with your custom reporter(s) (and *not* Ginkgo's default reporter), replace RunSpecs() with this method. Note that parallel tests will not work correctly without the default reporter

                                                func RunSpecsWithDefaultAndCustomReporters

                                                func RunSpecsWithDefaultAndCustomReporters(t GinkgoTestingT, description string, specReporters []Reporter) bool

                                                  To run your tests with Ginkgo's default reporter and your custom reporter(s), replace RunSpecs() with this method.

                                                  func Skip

                                                  func Skip(message string, callerSkip ...int)

                                                    Skip notifies Ginkgo that the current spec should be skipped.

                                                    func SynchronizedAfterSuite

                                                    func SynchronizedAfterSuite(allNodesBody interface{}, node1Body interface{}, timeout ...float64) bool

                                                      SynchronizedAfterSuite blocks complement the SynchronizedBeforeSuite blocks in solving the problem of setting up external singleton resources shared across nodes when running tests in parallel.

                                                      SynchronizedAfterSuite accomplishes this by taking *two* function arguments. The first runs on all nodes. The second runs only on parallel node #1 and *only* after all other nodes have finished and exited. This ensures that node 1, and any resources it is running, remain alive until all other nodes are finished.

                                                      Both functions have the same signature: either func() or func(done Done) to run asynchronously.

                                                      Here's a pseudo-code example that complements that given in SynchronizedBeforeSuite. Here, SynchronizedAfterSuite is used to tear down the shared database only after all nodes have finished:

                                                      var _ = SynchronizedAfterSuite(func() {
                                                      	dbClient.Cleanup()
                                                      }, func() {
                                                      	dbRunner.Stop()
                                                      })
                                                      

                                                      func SynchronizedBeforeSuite

                                                      func SynchronizedBeforeSuite(node1Body interface{}, allNodesBody interface{}, timeout ...float64) bool

                                                        SynchronizedBeforeSuite blocks are primarily meant to solve the problem of setting up singleton external resources shared across nodes when running tests in parallel. For example, say you have a shared database that you can only start one instance of that must be used in your tests. When running in parallel, only one node should set up the database and all other nodes should wait until that node is done before running.

                                                        SynchronizedBeforeSuite accomplishes this by taking *two* function arguments. The first is only run on parallel node #1. The second is run on all nodes, but *only* after the first function completes succesfully. Ginkgo also makes it possible to send data from the first function (on Node 1) to the second function (on all the other nodes).

                                                        The functions have the following signatures. The first function (which only runs on node 1) has the signature:

                                                        func() []byte
                                                        

                                                        or, to run asynchronously:

                                                        func(done Done) []byte
                                                        

                                                        The byte array returned by the first function is then passed to the second function, which has the signature:

                                                        func(data []byte)
                                                        

                                                        or, to run asynchronously:

                                                        func(data []byte, done Done)
                                                        

                                                        Here's a simple pseudo-code example that starts a shared database on Node 1 and shares the database's address with the other nodes:

                                                        var dbClient db.Client
                                                        var dbRunner db.Runner
                                                        
                                                        var _ = SynchronizedBeforeSuite(func() []byte {
                                                        	dbRunner = db.NewRunner()
                                                        	err := dbRunner.Start()
                                                        	Ω(err).ShouldNot(HaveOccurred())
                                                        	return []byte(dbRunner.URL)
                                                        }, func(data []byte) {
                                                        	dbClient = db.NewClient()
                                                        	err := dbClient.Connect(string(data))
                                                        	Ω(err).ShouldNot(HaveOccurred())
                                                        })
                                                        

                                                        func XContext

                                                        func XContext(text string, body func()) bool

                                                          You can mark the tests within a describe block as pending using XContext

                                                          func XDescribe

                                                          func XDescribe(text string, body func()) bool

                                                            You can mark the tests within a describe block as pending using XDescribe

                                                            func XIt

                                                            func XIt(text string, _ ...interface{}) bool

                                                              You can mark Its as pending using XIt

                                                              func XMeasure

                                                              func XMeasure(text string, _ ...interface{}) bool

                                                                You can mark Maeasurements as pending using XMeasure

                                                                Types

                                                                type Benchmarker

                                                                type Benchmarker interface {
                                                                	Time(name string, body func(), info ...interface{}) (elapsedTime time.Duration)
                                                                	RecordValue(name string, value float64, info ...interface{})
                                                                }

                                                                  Measurement tests receive a Benchmarker.

                                                                  You use the Time() function to time how long the passed in body function takes to run You use the RecordValue() function to track arbitrary numerical measurements. The optional info argument is passed to the test reporter and can be used to provide the measurement data to a custom reporter with context.

                                                                  See http://onsi.github.io/ginkgo/#benchmark_tests for more details

                                                                  type Done

                                                                  type Done chan<- interface{}

                                                                    Asynchronous specs are given a channel of the Done type. You must close or write to the channel to tell Ginkgo that your async test is done.

                                                                    type GinkgoTInterface

                                                                    type GinkgoTInterface interface {
                                                                    	Fail()
                                                                    	Error(args ...interface{})
                                                                    	Errorf(format string, args ...interface{})
                                                                    	FailNow()
                                                                    	Fatal(args ...interface{})
                                                                    	Fatalf(format string, args ...interface{})
                                                                    	Log(args ...interface{})
                                                                    	Logf(format string, args ...interface{})
                                                                    	Failed() bool
                                                                    	Parallel()
                                                                    	Skip(args ...interface{})
                                                                    	Skipf(format string, args ...interface{})
                                                                    	SkipNow()
                                                                    	Skipped() bool
                                                                    }

                                                                      The interface returned by GinkgoT(). This covers most of the methods in the testing package's T.

                                                                      func GinkgoT

                                                                      func GinkgoT(optionalOffset ...int) GinkgoTInterface

                                                                        Some matcher libraries or legacy codebases require a *testing.T GinkgoT implements an interface analogous to *testing.T and can be used if the library in question accepts *testing.T through an interface

                                                                        For example, with testify: assert.Equal(GinkgoT(), 123, 123, "they should be equal")

                                                                        Or with gomock: gomock.NewController(GinkgoT())

                                                                        GinkgoT() takes an optional offset argument that can be used to get the correct line number associated with the failure.

                                                                        type GinkgoTestDescription

                                                                        type GinkgoTestDescription struct {
                                                                        	FullTestText   string
                                                                        	ComponentTexts []string
                                                                        	TestText       string
                                                                        
                                                                        	IsMeasurement bool
                                                                        
                                                                        	FileName   string
                                                                        	LineNumber int
                                                                        
                                                                        	Failed bool
                                                                        }

                                                                          GinkgoTestDescription represents the information about the current running test returned by CurrentGinkgoTestDescription

                                                                          FullTestText: a concatenation of ComponentTexts and the TestText
                                                                          ComponentTexts: a list of all texts for the Describes & Contexts leading up to the current test
                                                                          TestText: the text in the actual It or Measure node
                                                                          IsMeasurement: true if the current test is a measurement
                                                                          FileName: the name of the file containing the current test
                                                                          LineNumber: the line number for the current test
                                                                          Failed: if the current test has failed, this will be true (useful in an AfterEach)
                                                                          

                                                                          func CurrentGinkgoTestDescription

                                                                          func CurrentGinkgoTestDescription() GinkgoTestDescription

                                                                            CurrentGinkgoTestDescripton returns information about the current running test.

                                                                            type GinkgoTestingT

                                                                            type GinkgoTestingT interface {
                                                                            	Fail()
                                                                            }

                                                                              The interface by which Ginkgo receives *testing.T

                                                                              type Reporter

                                                                              type Reporter reporters.Reporter

                                                                                Custom Ginkgo test reporters must implement the Reporter interface.

                                                                                The custom reporter is passed in a SuiteSummary when the suite begins and ends, and a SpecSummary just before a spec begins and just after a spec ends

                                                                                Source Files

                                                                                Directories

                                                                                Path Synopsis
                                                                                Ginkgo accepts a number of configuration options.
                                                                                Ginkgo accepts a number of configuration options.
                                                                                The Ginkgo CLI The Ginkgo CLI is fully documented [here](http://onsi.github.io/ginkgo/#the_ginkgo_cli) You can also learn more by running: ginkgo help Here are some of the more commonly used commands: To install: go install github.com/onsi/ginkgo/ginkgo To run tests: ginkgo To run tests in all subdirectories: ginkgo -r To run tests in particular packages: ginkgo <flags> /path/to/package /path/to/another/package To pass arguments/flags to your tests: ginkgo <flags> <packages> -- <pass-throughs> To run tests in parallel ginkgo -p this will automatically detect the optimal number of nodes to use.
                                                                                The Ginkgo CLI The Ginkgo CLI is fully documented [here](http://onsi.github.io/ginkgo/#the_ginkgo_cli) You can also learn more by running: ginkgo help Here are some of the more commonly used commands: To install: go install github.com/onsi/ginkgo/ginkgo To run tests: ginkgo To run tests in all subdirectories: ginkgo -r To run tests in particular packages: ginkgo <flags> /path/to/package /path/to/another/package To pass arguments/flags to your tests: ginkgo <flags> <packages> -- <pass-throughs> To run tests in parallel ginkgo -p this will automatically detect the optimal number of nodes to use.
                                                                                Ginkgo's Default Reporter A number of command line flags are available to tweak Ginkgo's default output.
                                                                                Ginkgo's Default Reporter A number of command line flags are available to tweak Ginkgo's default output.
                                                                                internal
                                                                                remote
                                                                                Aggregator is a reporter used by the Ginkgo CLI to aggregate and present parallel test output coherently as tests complete.
                                                                                Aggregator is a reporter used by the Ginkgo CLI to aggregate and present parallel test output coherently as tests complete.