ginkgo

README

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:

  • Nestable Describe and Context container blocks
  • BeforeEach and AfterEach blocks for setup and teardown
  • It blocks that hold your assertions
  • JustBeforeEach blocks that separate creation from configuration (also known as the subject action pattern).

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

  • Write custom reporters (for example, Ginkgo comes with a JUnit XML reporter)
  • Adapt an existing matcher library (or write your own!) to work with Ginkgo

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:

• testify
• gocheck

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:

• Ginkgo ;)
• GoConvey
• Goblin
• Mao
• Zen

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

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
• func AfterEach(body interface{}, timeout ...float64) bool
• func BeforeEach(body interface{}, timeout ...float64) bool
• func Context(text string, body func()) bool
• func Describe(text string, body func()) bool
• func FContext(text string, body func()) bool
• func FDescribe(text string, body func()) bool
• func FIt(text string, body interface{}, timeout ...float64) bool
• func FMeasure(text string, body func(Benchmarker), samples int) bool
• func Fail(message string, callerSkip ...int)
• func GinkgoT(optionalOffset ...int) *ginkgoTestingTProxy
• func It(text string, body interface{}, timeout ...float64) bool
• func JustBeforeEach(body interface{}, timeout ...float64) bool
• func Measure(text string, body func(Benchmarker), samples int) bool
• func PContext(text string, body func()) bool
• func PDescribe(text string, body func()) bool
• func PIt(text string, _ ...interface{}) bool
• func PMeasure(text string, _ ...interface{}) bool
• func RunSpecs(t GinkgoTestingT, description string) bool
• func RunSpecsWithCustomReporters(t GinkgoTestingT, description string, specReporters []Reporter) bool
• func RunSpecsWithDefaultAndCustomReporters(t GinkgoTestingT, description string, specReporters []Reporter) bool
• func XContext(text string, body func()) bool
• func XDescribe(text string, body func()) bool
• func XIt(text string, _ ...interface{}) bool
• func XMeasure(text string, _ ...interface{}) bool
• type Benchmarker
• type Done
• type GinkgoTestDescription
  • func CurrentGinkgoTestDescription() GinkgoTestDescription
• type GinkgoTestingT
• type Reporter

Constants

const GINKGO_VERSION = config.VERSION

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, BeforeEach blocks can be made asynchronous by providing a body function that accepts a Done channel

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 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 func(Benchmarker), 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 GinkgoT

func GinkgoT(optionalOffset ...int) *ginkgoTestingTProxy

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")

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

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 alos 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 func(Benchmarker), 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.

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 Go Test... 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.

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 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, alongside a custom reporter, to provide the measurement data with context.

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

type Done

type Done chan<- interface{}

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

type GinkgoTestDescription

type GinkgoTestDescription struct {
	ComponentTexts []string
	FullTestText   string
	TestText       string

	IsMeasurement bool

	FileName   string
	LineNumber int
}

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

ComponentTexts: a list of all texts for the Describes & Contexts leading up to the current test
FullTestText: a concatenation of ComponentTexts
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

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 an ExmapleSummary just before an example (spec) begins and just after an example (spec) ends