ginkgo

Documentation

Index

• Constants
• Variables
• func AfterEach(args ...interface{}) bool
• func AfterSuite(body func()) bool
• func BeforeEach(args ...interface{}) bool
• func BeforeSuite(body func()) bool
• func By(text string, callbacks ...func())
• func Describe(text string, args ...interface{}) bool
• func FDescribe(text string, args ...interface{}) bool
• func FIt(text string, args ...interface{}) bool
• func Fail(message string, callerSkip ...int)
• func GinkgoConfiguration() (types.SuiteConfig, types.ReporterConfig)
• func GinkgoParallelNode() int
• func GinkgoRandomSeed() int64
• func GinkgoRecover()
• func It(text string, args ...interface{}) bool
• func JustAfterEach(args ...interface{}) bool
• func JustBeforeEach(args ...interface{}) bool
• func Measure(_ ...interface{}) bool
• func PDescribe(text string, args ...interface{}) bool
• func PIt(text string, args ...interface{}) bool
• func ReportAfterEach(body func(SpecReport)) bool
• func ReportAfterSuite(text string, body func(Report)) bool
• func RunSpecs(t GinkgoTestingT, description string) bool
• func RunSpecsWithCustomReporters(t GinkgoTestingT, description string, _ []Reporter) bool
• func RunSpecsWithDefaultAndCustomReporters(t GinkgoTestingT, description string, _ []Reporter) bool
• func Skip(message string, callerSkip ...int)
• func SynchronizedAfterSuite(allNodesBody func(), node1Body func()) bool
• func SynchronizedBeforeSuite(node1Body func() []byte, allNodesBody func([]byte)) bool
• type Benchmarker
• type DeprecatedGinkgoTestDescription
  • func CurrentGinkgoTestDescription() DeprecatedGinkgoTestDescription
• type Done
• type FlakeAttempts
• type GinkgoTInterface
  • func GinkgoT(optionalOffset ...int) GinkgoTInterface
• type GinkgoTestDescription
• type GinkgoTestingT
• type GinkgoWriterInterface
• type Offset
• type Report
• type Reporter
• type SpecReport
  • func CurrentSpecReport() SpecReport

Constants

const Focus = internal.Focus

Focus is a decorator that allows you to mark a test or container as focused. Identical to FIt and FDescribe.

const GINKGO_VERSION = types.VERSION

const Pending = internal.Pending

Pending is a decorator that allows you to mark a test or container as pending. Identical to PIt and PDescribe.

Variables

var Context, FContext, PContext, XContext = Describe, FDescribe, PDescribe, XDescribe

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

In addition you can nest Describe, Context and When blocks. Describe, Context and When 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 and Whens.

var Specify, FSpecify, PSpecify, XSpecify = It, FIt, PIt, XIt

Specify blocks are aliases for It blocks and allow for more natural wording in situations which "It" does not fit into a natural sentence flow. All the same protocols apply for Specify blocks which apply to It blocks.

var When, FWhen, PWhen, XWhen = Describe, FDescribe, PDescribe, XDescribe

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

In addition you can nest Describe, Context and When blocks. Describe, Context and When 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 and Whens.

var XDescribe = PDescribe

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

var XIt = PIt

You can mark Its as pending using XIt

Functions

func AfterEach

func AfterEach(args ...interface{}) 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.

func AfterSuite

func AfterSuite(body func()) 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.

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(args ...interface{}) 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.

func BeforeSuite

func BeforeSuite(body func()) bool

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

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, 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 Describe

func Describe(text string, args ...interface{}) bool

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

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

func FDescribe

func FDescribe(text string, args ...interface{}) bool

You can focus the tests within a describe block using FDescribe

func FIt

func FIt(text string, args ...interface{}) bool

You can focus individual Its using FIt

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 GinkgoConfiguration

func GinkgoConfiguration() (types.SuiteConfig, types.ReporterConfig)

GinkgoConfiguration returns the configuration of the currenty running test suite

func GinkgoParallelNode

func GinkgoParallelNode() int

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

func GinkgoRandomSeed

func GinkgoRandomSeed() int64

GinkgoRandomSeed returns the seed used to randomize spec execution order. It is useful for seeding your own pseudorandom number generators (PRNGs) to ensure consistent executions from run to run, where your tests contain variability (for example, when selecting random test data).

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, args ...interface{}) bool

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

func JustAfterEach

func JustAfterEach(args ...interface{}) bool

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

func JustBeforeEach

func JustBeforeEach(args ...interface{}) 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_)

func Measure

func Measure(_ ...interface{}) bool

deprecated Measure

func PDescribe

func PDescribe(text string, args ...interface{}) bool

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

func PIt

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

You can mark Its as pending using PIt

func ReportAfterEach

func ReportAfterEach(body func(SpecReport)) bool

ReportAfterEach nodes are run for each test, even if the test is skipped or pending. ReportAfterEach nodes take a function that receives a types.SpecReport. They are called after the test has completed and are passed in the final report for the test.

func ReportAfterSuite

func ReportAfterSuite(text string, body func(Report)) bool

ReportAfterSuite nodes are run at the end of the suite. ReportAfterSuite nodes take a function that receives a types.Report. They are called at the end of the suite, after all specs have run and any AfterSuite or SynchronizedAfterSuite nodes, and are passed in the final report for the test suite. ReportAftersuite nodes must be created at the top-level (i.e. not nested in a Context/Describe/When node)

When running in parallel, Ginkgo ensures that only one of the parallel nodes runs the ReportAfterSuite and that it is passed a report that is aggregated across all parallel nodes

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, _ []Reporter) bool

Deprecated: Custom Reporters have been removed in v2. RunSpecsWithCustomReporters will simply call RunSpecs()

Please read the documentation at: https://github.com/onsi/ginkgo/blob/v2/docs/MIGRATING_TO_V2.md#removed-custom-reporters for Ginkgo's new behavior and for a migration path.

func RunSpecsWithDefaultAndCustomReporters

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

Deprecated: Custom Reporters have been removed in v2. RunSpecsWithDefaultAndCustomReporters will simply call RunSpecs()

Please read the documentation at: https://github.com/onsi/ginkgo/blob/v2/docs/MIGRATING_TO_V2.md#removed-custom-reporters for Ginkgo's new behavior and for a migration path.

func Skip

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

Skip notifies Ginkgo that the current spec was skipped.

func SynchronizedAfterSuite

func SynchronizedAfterSuite(allNodesBody func(), node1Body func()) 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.

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 func() []byte, allNodesBody func([]byte)) 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 successfully. 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

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

func(data []byte)

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())
})

Types

type Benchmarker

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

deprecated benchmarker

type DeprecatedGinkgoTestDescription

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

	FileName   string
	LineNumber int

	Failed   bool
	Duration time.Duration
}

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 It node
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)

Deprecated: Use CurrentSpecReport() instead

func CurrentGinkgoTestDescription

func CurrentGinkgoTestDescription() DeprecatedGinkgoTestDescription

CurrentGinkgoTestDescripton returns information about the current running test. Deprecated: Use CurrentSpecReport() instead

type Done

type Done = internal.Done

Deprecated Done Channel for asynchronous testing

type FlakeAttempts

type FlakeAttempts = internal.FlakeAttempts

FlakeAttempts(uint N) is a decorator that allows you to mark individual tests or test containers as flaky. Ginkgo will run them up to `N` times until they pass.

type GinkgoTInterface

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

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 = DeprecatedGinkgoTestDescription

type GinkgoTestingT

type GinkgoTestingT interface {
	Fail()
}

The interface by which Ginkgo receives *testing.T

type GinkgoWriterInterface

type GinkgoWriterInterface interface {
	io.Writer

	Print(a ...interface{})
	Printf(format string, a ...interface{})
	Println(a ...interface{})

	TeeTo(writer io.Writer)
	ClearTeeWriters()
}

var GinkgoWriter GinkgoWriterInterface

GinkgoWriter implements a GinkgoWriterInterface and 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.

GinkgoWriter also provides convenience `Print`, `Printf` and `Println` methods. Running `GinkgoWriter.Print*(...)` is equivalent to `fmt.Fprint*(GinkgoWriter, ...)`

GinkgoWriter also allows you to tee to a custom writer via `GinkgoWriter.TeeTo(writer)`. Once registered via `TeeTo`, the `writer` will receive _any_ data You can unregister all Tee'd Writers with `GinkgoWRiter.ClearTeeWriters()` written to `GinkgoWriter` regardless of whether the test succeeded or failed.

type Offset

type Offset = internal.Offset

Offset(uint) is a decorator that allows you to change the stack-frame offset used when computing the line number of the node in question.

type Report

type Report = types.Report

type Reporter

type Reporter = reporters.DeprecatedReporter

Deprecated: Custom Ginkgo test reporters are no longer supported Please read the documentation at: https://github.com/onsi/ginkgo/blob/v2/docs/MIGRATING_TO_V2.md#removed-custom-reporters for Ginkgo's new behavior and for a migration path.

type SpecReport

type SpecReport = types.SpecReport

func CurrentSpecReport

func CurrentSpecReport() SpecReport

CurrentSpecReport returns information about the current running test. The returned object is a types.SpecReport which includes helper methods to make extracting information about the test easier.