ginkgo

package module
v2.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 30, 2021 License: MIT Imports: 15 Imported by: 2,544

README

Ginkgo

test | Ginkgo Docs

Ginkgo 2.0 is now Generally Available!

You can learn more about 2.0 in the Migration Guide!

Ginkgo is a mature testing framework for Go designed to help you write expressive specs. Ginkgo builds on top of Go's testing foundation and is complemented by the Gomega matcher library. Together, Ginkgo and Gomega let you express the intent behind your specs clearly:

import (
    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    ...
)

Describe("Checking books out of the library", Label("library"), func() {
    var library *libraries.Library
    var book *books.Book
    var valjean *users.User
    BeforeEach(func() {
        library = libraries.NewClient()
        book = &books.Book{
            Title: "Les Miserables",
            Author: "Victor Hugo",
        }
        valjean = users.NewUser("Jean Valjean")
    })

    When("the library has the book in question", func() {
        BeforeEach(func() {
            Expect(library.Store(book)).To(Succeed())
        })

        Context("and the book is available", func() {
            It("lends it to the reader", func() {
                Expect(valjean.Checkout(library, "Les Miserables")).To(Succeed())
                Expect(valjean.Books()).To(ContainElement(book))
                Expect(library.UserWithBook(book)).To(Equal(valjean))
            })
        })

        Context("but the book has already been checked out", func() {
            var javert *users.User
            BeforeEach(func() {
                javert = users.NewUser("Javert")
                Expect(javert.Checkout(library, "Les Miserables")).To(Succeed())
            })

            It("tells the user", func() {
                err := valjean.Checkout(library, "Les Miserables")
                Expect(error).To(MatchError("Les Miserables is currently checked out"))
            })

            It("lets the user place a hold and get notified later", func() {
                Expect(valjean.Hold(library, "Les Miserables")).To(Succeed())
                Expect(valjean.Holds()).To(ContainElement(book))

                By("when Javert returns the book")
                Expect(javert.Return(library, book)).To(Succeed())

                By("it eventually informs Valjean")
                notification := "Les Miserables is ready for pick up"
                Eventually(valjean.Notifications).Should(ContainElement(notification))

                Expect(valjean.Checkout(library, "Les Miserables")).To(Succeed())
                Expect(valjean.Books()).To(ContainElement(book))
                Expect(valjean.Holds()).To(BeEmpty())
            })
        })  
    })

    When("the library does not have the book in question", func() {
        It("tells the reader the book is unavailable", func() {
            err := valjean.Checkout(library, "Les Miserables")
            Expect(error).To(MatchError("Les Miserables is not in the library catalog"))
        })
    })
})

Jump to the docs to learn more. It's easy to bootstrap and start writing your first specs.

If you have a question, comment, bug report, feature request, etc. please open a GitHub issue, or visit the Ginkgo Slack channel.

Capabilities

Whether writing basic unit specs, complex integration specs, or even performance specs - Ginkgo gives you an expressive Domain-Specific Language (DSL) that will be familiar to users coming from frameworks such as Quick, RSpec, Jasmine, and Busted. This style of testing is sometimes referred to as "Behavior-Driven Development" (BDD) though Ginkgo's utility extends beyond acceptance-level testing.

With Ginkgo's DSL you can use nestable Describe, Context and When container nodes to help you organize your specs. BeforeEach and AfterEach setup nodes for setup and cleanup. It and Specify subject nodes that hold your assertions. BeforeSuite and AfterSuite nodes to prep for and cleanup after a suite... and much more!

At runtime, Ginkgo can run your specs in reproducibly random order and has sophisticated support for spec parallelization. In fact, running specs in parallel is as easy as

ginkgo -p

By following established patterns for writing parallel specs you can build even large, complex integration suites that parallelize cleanly and run performantly.

As your suites grow Ginkgo helps you keep your specs organized with labels and lets you easily run subsets of specs, either programatically or on the command line. And Ginkgo's reporting infrastructure generates machine-readable output in a variety of formats and allows you to build your own custom reporting infrastructure.

Ginkgo ships with ginkgo, a command line tool with support for generating, running, filtering, and profiling Ginkgo suites. You can even have Ginkgo automatically run your specs when it detects a change with ginkgo watch, enabling rapid feedback loops during test-driven development.

And that's just Ginkgo! Gomega brings a rich, mature, family of assertions and matchers to your suites. With Gomega you can easily mix synchronous and asynchronous assertions in your specs. You can even build your own set of expressive domain-specific matchers quickly and easily by composing Gomega's existing building blocks.

Happy Testing!

License

Ginkgo is MIT-Licensed

Contributing

See CONTRIBUTING.md

Documentation

Overview

Ginkgo is a testing framework for Go designed to help you write expressive tests. https://github.com/onsi/ginkgo MIT-Licensed

The godoc documentation outlines Ginkgo's API. Since Ginkgo is a Domain-Specific Language it is important to build a mental model for Ginkgo - the narrative documentation at https://onsi.github.io/ginkgo/ is designed to help you do that. You should start there - even a brief skim will be helpful. At minimum you should skim through the https://onsi.github.io/ginkgo/#getting-started chapter.

Ginkgo's is best paired with the Gomega matcher library: https://github.com/onsi/gomega

You can run Ginkgo specs with go test - however we recommend using the ginkgo cli. It enables functionality that go test does not (especially running suites in parallel). You can learn more at https://onsi.github.io/ginkgo/#ginkgo-cli-overview or by running 'ginkgo help'.

Index

Constants

View Source 
const Focus = internal.Focus

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

You can learn more here: https://onsi.github.io/ginkgo/#filtering-specs You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

View Source 
const GINKGO_VERSION = types.VERSION
View Source 
const OncePerOrdered = internal.OncePerOrdered

OncePerOrdered is a decorator that allows you to mark outer BeforeEach, AfterEach, JustBeforeEach, and JustAfterEach setup nodes to run once per ordered context. Normally these setup nodes run around each individual spec, with OncePerOrdered they will run once around the set of specs in an ordered container. The behavior for non-Ordered containers/specs is unchanged.

You can learh more here: https://onsi.github.io/ginkgo/#setup-around-ordered-containers-the-onceperordered-decorator You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

View Source 
const Ordered = internal.Ordered

Ordered is a decorator that allows you to mark a container as ordered. Tests in the container will always run in the order they appear. They will never be randomized and they will never run in parallel with one another, though they may run in parallel with other specs.

You can learn more here: https://onsi.github.io/ginkgo/#ordered-containers You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

View Source 
const Pending = internal.Pending

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

You can learn more here: https://onsi.github.io/ginkgo/#filtering-specs You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

View Source 
const ReportEntryVisibilityAlways, ReportEntryVisibilityFailureOrVerbose, ReportEntryVisibilityNever = types.ReportEntryVisibilityAlways, types.ReportEntryVisibilityFailureOrVerbose, types.ReportEntryVisibilityNever
View Source 
const Serial = internal.Serial

Serial is a decorator that allows you to mark a spec or container as serial. These specs will never run in parallel with other specs. Tests in ordered containers cannot be marked as serial - mark the ordered container instead.

You can learn more here: https://onsi.github.io/ginkgo/#serial-specs You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

Variables

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

Context is an alias for Describe - it generates the exact same kind of Container node

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

Specify is an alias for It - it can allow for more natural wording in some context.

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

When is an alias for Describe - it generates the exact same kind of Container node

View Source 
var XDescribe = PDescribe

XDescribe marks specs within the Describe block as pending.

XDescribe is an alias for PDescribe

View Source 
var XDescribeTable = PDescribeTable

You can mark a table as pending with `XDescribeTable`. This is equivalent to `XDescribe`.

View Source 
var XEntry = PEntry

You can mark a particular entry as pending with XEntry. This is equivalent to XIt.

View Source 
var XIt = PIt

XIt allows you to mark an individual It as pending.

XIt is an alias for PIt

Functions

func AbortSuite 

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

AbortSuite instructs Ginkgo to fail the current spec and skip all subsequent specs, thereby aborting the suite.

You can call AbortSuite in any Setup or Subject node closure.

You can learn more about how Ginkgo handles suite interruptions here: https://onsi.github.io/ginkgo/#interrupting-aborting-and-timing-out-suites

func AddReportEntry 

func AddReportEntry(name string, args ...interface{})

AddReportEntry generates and adds a new ReportEntry to the current spec's SpecReport. It can take any of the following arguments:

  • A single arbitrary object to attach as the Value of the ReportEntry. This object will be included in any generated reports and will be emitted to the console when the report is emitted.
  • A ReportEntryVisibility enum to control the visibility of the ReportEntry
  • An Offset or CodeLocation decoration to control the reported location of the ReportEntry

If the Value object implements `fmt.Stringer`, it's `String()` representation is used when emitting to the console.

AddReportEntry() must be called within a Subject or Setup node - not in a Container node.

You can learn more about Report Entries here: https://onsi.github.io/ginkgo/#attaching-data-to-reports

func AfterAll 

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

AfterAll nodes are Setup nodes that can occur inside Ordered contaienrs. They run just once after all specs in the Ordered container have run.

Multiple AfterAll nodes can be defined in a given Ordered container however they cannot be nested inside any other container.

Note that you can also use DeferCleanup() in a BeforeAll node to accomplish similar behavior.

You cannot nest any other Ginkgo nodes within an AfterAll node's closure. You can learn more about Ordered Containers at: https://onsi.github.io/ginkgo/#ordered-containers And you can learn more about AfterAll at: https://onsi.github.io/ginkgo/#setup-in-ordered-containers-beforeall-and-afterall

func AfterEach 

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

AfterEach nodes are Setup nodes whose closures run after It node closures. When multiple AfterEach nodes are defined in nested Container nodes the innermost AfterEach node closures are run first.

Note that you can also use DeferCleanup() in other Setup or Subject nodes to accomplish similar results.

You cannot nest any other Ginkgo nodes within an AfterEach node's closure. You can learn more here: https://onsi.github.io/ginkgo/#spec-cleanup-aftereach-and-defercleanup

func AfterSuite 

func AfterSuite(body func()) bool

AfterSuite nodes are suite-level Setup nodes run after all specs have finished - regardless of whether specs have passed or failed. AfterSuite node closures always run, even if Ginkgo receives an interrupt signal (^C), in order to ensure cleanup occurs.

When running in parallel, each parallel 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.

You cannot nest any other Ginkgo nodes within an AfterSuite node's closure. You can learn more here: https://onsi.github.io/ginkgo/#suite-setup-and-cleanup-beforesuite-and-aftersuite

func BeforeAll 

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

BeforeAll nodes are Setup nodes that can occur inside Ordered contaienrs. They run just once before any specs in the Ordered container run.

Multiple BeforeAll nodes can be defined in a given Ordered container however they cannot be nested inside any other container.

You cannot nest any other Ginkgo nodes within a BeforeAll node's closure. You can learn more about Ordered Containers at: https://onsi.github.io/ginkgo/#ordered-containers And you can learn more about BeforeAll at: https://onsi.github.io/ginkgo/#setup-in-ordered-containers-beforeall-and-afterall

func BeforeEach 

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

BeforeEach nodes are Setup nodes whose closures run before It node closures. When multiple BeforeEach nodes are defined in nested Container nodes the outermost BeforeEach node closures are run first.

You cannot nest any other Ginkgo nodes within a BeforeEach node's closure. You can learn more here: https://onsi.github.io/ginkgo/#extracting-common-setup-beforeeach

func BeforeSuite 

func BeforeSuite(body func()) bool

BeforeSuite nodes are suite-level Setup nodes that run just once before any specs are run. When running in parallel, each parallel 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.

You cannot nest any other Ginkgo nodes within a BeforeSuite node's closure. You can learn more here: https://onsi.github.io/ginkgo/#suite-setup-and-cleanup-beforesuite-and-aftersuite

func By 

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

By allows you to better document complex Specs.

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 complex or lengthy workflows.

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

By will also generate and attach a ReportEntry to the spec. This will ensure that By annotations appear in Ginkgo's machine-readable reports.

Note that By does not generate a new Ginkgo node - rather it is simply synctactic sugar around GinkgoWriter and AddReportEntry You can learn more about By here: https://onsi.github.io/ginkgo/#documenting-complex-specs-by

func DeferCleanup 

func DeferCleanup(args ...interface{})

DeferCleanup can be called within any Setup or Subject node to register a cleanup callback that Ginkgo will call at the appropriate time to cleanup after the spec.

DeferCleanup can be passed: 1. A function that takes no arguments and returns no values. 2. A function that returns an error (in which case it will assert that the returned error was nil, or it will fail the spec). 3. A function that takes arguments (and optionally returns an error) followed by a list of arguments to passe to the function. For example: 

BeforeEach(func() {
    DeferCleanup(os.SetEnv, "FOO", os.GetEnv("FOO"))
    os.SetEnv("FOO", "BAR")
})

will register a cleanup handler that will set the environment variable "FOO" to it's current value (obtained by os.GetEnv("FOO")) after the spec runs and then sets the environment variable "FOO" to "BAR" for the current spec.

When DeferCleanup is called in BeforeEach, JustBeforeEach, It, AfterEach, or JustAfterEach the registered callback will be invoked when the spec completes (i.e. it will behave like an AfterEach node) When DeferCleanup is called in BeforeAll or AfterAll the registered callback will be invoked when the ordered container completes (i.e. it will behave like an AfterAll node) When DeferCleanup is called in BeforeSuite, SynchronizedBeforeSuite, AfterSuite, or SynchronizedAfterSuite the registered callback will be invoked when the suite completes (i.e. it will behave like an AfterSuite node)

Note that DeferCleanup does not represent a node but rather dynamically generates the appropriate type of cleanup node based on the context in which it is called. As such you must call DeferCleanup within a Setup or Subject node, and not within a Container node. You can learn more about DeferCleanup here: https://onsi.github.io/ginkgo/#cleaning-up-our-cleanup-code-defercleanup

func Describe 

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

Describe nodes are Container nodes that allow you to organize your specs. A Describe node's closure can contain any number of Setup nodes (e.g. BeforeEach, AfterEach, JustBeforeEach), and Subject nodes (i.e. It).

Context and When nodes are aliases for Describe - use whichever gives your suite a better narrative flow. It is idomatic to Describe the behavior of an object or function and, within that Describe, outline a number of Contexts and Whens.

You can learn more at https://onsi.github.io/ginkgo/#organizing-specs-with-container-nodes In addition, container nodes can be decorated with a variety of decorators. You can learn more here: https://onsi.github.io/ginkgo/#decorator-reference

func DescribeTable 

func DescribeTable(description string, args ...interface{}) bool

DescribeTable describes a table-driven spec.

For example: 

DescribeTable("a simple table",
    func(x int, y int, expected bool) {
        Ω(x > y).Should(Equal(expected))
    },
    Entry("x > y", 1, 0, true),
    Entry("x == y", 0, 0, false),
    Entry("x < y", 0, 1, false),
)

You can learn more about DescribeTable here: https://onsi.github.io/ginkgo/#table-specs And can explore some Table patterns here: https://onsi.github.io/ginkgo/#table-specs-patterns

func FDescribe 

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

FDescribe focuses specs within the Describe block.

func FDescribeTable 

func FDescribeTable(description string, args ...interface{}) bool

You can focus a table with `FDescribeTable`. This is equivalent to `FDescribe`.

func FIt 

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

FIt allows you to focus an individual It.

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

Under the hood, Fail panics to end execution of the current spec. Ginkgo will catch this panic and proceed with the subsequent spec. If you call Fail, or make an assertion, within a goroutine launched by your spec you must add defer GinkgoRecover() to the goroutine to catch the panic emitted by Fail.

You can call Fail in any Setup or Subject node closure.

You can learn more about how Ginkgo manages failures here: https://onsi.github.io/ginkgo/#mental-model-how-ginkgo-handles-failure

func GinkgoConfiguration 

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

GinkgoConfiguration returns the configuration of the current suite.

The first return value is the SuiteConfig which controls aspects of how the suite runs, the second return value is the ReporterConfig which controls aspects of how Ginkgo's default reporter emits output.

Mutating the returned configurations has no effect. To reconfigure Ginkgo programatically you need to pass in your mutated copies into RunSpecs().

You can learn more at https://onsi.github.io/ginkgo/#overriding-ginkgos-command-line-configuration-in-the-suite

func GinkgoParallelNode deprecated 

func GinkgoParallelNode() int

Deprecated: GinkgoParallelNode() has been renamed to GinkgoParallelProcess()

func GinkgoParallelProcess 

func GinkgoParallelProcess() int

GinkgoParallelProcess returns the parallel process number for the current ginkgo process The process number is 1-indexed. You can use GinkgoParallelProcess() to shard access to shared resources across your suites. You can learn more about patterns for sharding at https://onsi.github.io/ginkgo/#patterns-for-parallel-integration-specs

For more on how specs are parallelized in Ginkgo, see http://onsi.github.io/ginkgo/#spec-parallelization

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 to ensure consistent executions from run to run, where your tests contain variability (for example, when selecting random spec data).

You can learn more at https://onsi.github.io/ginkgo/#spec-randomization

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. Normally, Ginkgo recovers the panic for you, however if a panic originates on a goroutine *launched* from one of your specs 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.

You can learn more about how Ginkgo manages failures here: https://onsi.github.io/ginkgo/#mental-model-how-ginkgo-handles-failure

func It 

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

It nodes are Subject nodes that contain your spec code and assertions.

Each It node corresponds to an individual Ginkgo spec. You cannot nest any other Ginkgo nodes within an It node's closure.

You can learn more at https://onsi.github.io/ginkgo/#spec-subjects-it In addition, subject nodes can be decorated with a variety of decorators. You can learn more here: https://onsi.github.io/ginkgo/#decorator-reference

func JustAfterEach 

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

JustAfterEach nodes are similar to AfterEach nodes, however they are guaranteed to run *before* all AfterEach node closures - just after the It node closure. This can allow you to separate diagnostics collection from teardown for a spec.

You cannot nest any other Ginkgo nodes within a JustAfterEach node's closure. You can learn more and see some examples here: https://onsi.github.io/ginkgo/#separating-diagnostics-collection-and-teardown-justaftereach

func JustBeforeEach 

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

JustBeforeEach nodes are similar to BeforeEach nodes, however they are guaranteed to run *after* all BeforeEach node closures - just before the It node closure. This can allow you to separate configuration from creation of resources for a spec.

You cannot nest any other Ginkgo nodes within a JustBeforeEach node's closure. You can learn more and see some examples here: https://onsi.github.io/ginkgo/#separating-creation-and-configuration-justbeforeeach

func Measure deprecated 

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

Deprecated: Measure() has been removed from Ginkgo 2.0

Use Gomega's gmeasure package instead. You can learn more here: https://onsi.github.io/ginkgo/#benchmarking-code

func PDescribe 

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

PDescribe marks specs within the Describe block as pending.

func PDescribeTable 

func PDescribeTable(description string, args ...interface{}) bool

You can mark a table as pending with `PDescribeTable`. This is equivalent to `PDescribe`.

func PIt 

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

PIt allows you to mark an individual It as pending.

func PauseOutputInterception 

func PauseOutputInterception()

PauseOutputInterception() pauses Ginkgo's output interception. This is only relevant when running in parallel and output to stdout/stderr is being intercepted. You generally don't need to call this function - however there are cases when Ginkgo's output interception mechanisms can interfere with external processes launched by the test process.

In particular, if an external process is launched that has cmd.Stdout/cmd.Stderr set to os.Stdout/os.Stderr then Ginkgo's output interceptor will hang. To circumvent this, set cmd.Stdout/cmd.Stderr to GinkgoWriter. If, for some reason, you aren't able to do that, you can PauseOutputInterception() before starting the process then ResumeOutputInterception() after starting it.

Note that PauseOutputInterception() does not cause stdout writes to print to the console - this simply stops intercepting and storing stdout writes to an internal buffer.

func ReportAfterEach 

func ReportAfterEach(body func(SpecReport)) bool

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

You cannot nest any other Ginkgo nodes within a ReportAfterEach node's closure. You can learn more about ReportAfterEach here: https://onsi.github.io/ginkgo/#generating-reports-programmatically

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

In addition to using ReportAfterSuite to programatically generate suite reports, you can also generate JSON, JUnit, and Teamcity formatted reports using the --json-report, --junit-report, and --teamcity-report ginkgo CLI flags.

You cannot nest any other Ginkgo nodes within a ReportAfterSuite node's closure. You can learn more about ReportAfterSuite here: https://onsi.github.io/ginkgo/#generating-reports-programmatically You can learn more about Ginkgo's reporting infrastructure, including generating reports with the CLI here: https://onsi.github.io/ginkgo/#generating-machine-readable-reports

func ReportBeforeEach 

func ReportBeforeEach(body func(SpecReport)) bool

ReportBeforeEach nodes are run for each spec, even if the spec is skipped or pending. ReportBeforeEach nodes take a function that receives a SpecReport. They are called before the spec starts.

You cannot nest any other Ginkgo nodes within a ReportBeforeEach node's closure. You can learn more about ReportBeforeEach here: https://onsi.github.io/ginkgo/#generating-reports-programmatically

func ResumeOutputInterception 

func ResumeOutputInterception()

ResumeOutputInterception() - see docs for PauseOutputInterception()

func RunSpecs 

func RunSpecs(t GinkgoTestingT, description string, args ...interface{}) bool

RunSpecs is the entry point for the Ginkgo spec runner.

You must call this within a Golang testing TestX(t *testing.T) function. If you bootstrapped your suite with "ginkgo bootstrap" this is already done for you.

Ginkgo is typically configured via command-line flags. This configuration can be overriden, however, and passed into RunSpecs as optional arguments: 

func TestMySuite(t *testing.T)  {
	RegisterFailHandler(gomega.Fail)
	// fetch the current config
	suiteConfig, reporterConfig := GinkgoConfiguration()
	// adjust it
	suiteConfig.SkipStrings = []string{"NEVER-RUN"}
	reporterConfig.FullTrace = true
	// pass it in to RunSpecs
	RunSpecs(t, "My Suite", suiteConfig, reporterConfig)
}

Note that some configuration changes can lead to undefined behavior. For example, you should not change ParallelProcess or ParallelTotal as the Ginkgo CLI is responsible for setting these and orchestrating parallel specs across the parallel processes. See http://onsi.github.io/ginkgo/#spec-parallelization for more on how specs are parallelized in Ginkgo.

You can also pass suite-level Label() decorators to RunSpecs. The passed-in labels will apply to all specs in the suite.

func RunSpecsWithCustomReporters deprecated 

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

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

Use Ginkgo's reporting nodes instead and 2.0 reporting infrastructure instead. You can learn more here: https://onsi.github.io/ginkgo/#reporting-infrastructure For a migration guide see: https://onsi.github.io/ginkgo/MIGRATING_TO_V2#removed-custom-reporters

func RunSpecsWithDefaultAndCustomReporters deprecated 

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

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

Use Ginkgo's reporting nodes instead and 2.0 reporting infrastructure instead. You can learn more here: https://onsi.github.io/ginkgo/#reporting-infrastructure For a migration guide see: https://onsi.github.io/ginkgo/MIGRATING_TO_V2#removed-custom-reporters

func Skip 

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

Skip instructs Ginkgo to skip the current spec

You can call Skip in any Setup or Subject node closure.

For more on how to filter specs in Ginkgo see https://onsi.github.io/ginkgo/#filtering-specs

func SynchronizedAfterSuite 

func SynchronizedAfterSuite(allProcessBody func(), process1Body func()) bool

SynchronizedAfterSuite nodes complement the SynchronizedBeforeSuite nodes in solving the problem of splitting clean up into a piece that runs on all processes and a piece that must only run once - on process #1.

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

Note that you can also use DeferCleanup() in SynchronizedBeforeSuite to accomplish similar results.

You cannot nest any other Ginkgo nodes within an SynchronizedAfterSuite node's closure. You can learn more, and see some examples, here: https://onsi.github.io/ginkgo/#parallel-suite-setup-and-cleanup-synchronizedbeforesuite-and-synchronizedaftersuite

func SynchronizedBeforeSuite 

func SynchronizedBeforeSuite(process1Body func() []byte, allProcessBody func([]byte)) bool

SynchronizedBeforeSuite nodes allow you to perform some of the suite setup just once - on parallel process #1 - and then pass information from that setup to the rest of the suite setup on all processes. This is useful for performing expensive or singleton setup once, then passing information from that setup to all parallel processes.

SynchronizedBeforeSuite accomplishes this by taking *two* function arguments and passing data between them. The first function is only run on parallel process #1. The second is run on all processes, but *only* after the first function completes successfully. The functions have the following signatures:

The first function (which only runs on process #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)

You cannot nest any other Ginkgo nodes within an SynchronizedBeforeSuite node's closure. You can learn more, and see some examples, here: https://onsi.github.io/ginkgo/#parallel-suite-setup-and-cleanup-synchronizedbeforesuite-and-synchronizedaftersuite

Types

type Benchmarker deprecated 

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 has been removed from Ginkgo 2.0

Use Gomega's gmeasure package instead. You can learn more here: https://onsi.github.io/ginkgo/#benchmarking-code

type DeprecatedGinkgoTestDescription deprecated 

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

	FileName   string
	LineNumber int

	Failed   bool
	Duration time.Duration
}

Deprecated: GinkgoTestDescription has been replaced with SpecReport.

Use CurrentSpecReport() instead. You can learn more here: https://onsi.github.io/ginkgo/#getting-a-report-for-the-current-spec The SpecReport type is documented here: https://pkg.go.dev/github.com/onsi/ginkgo/v2/types#SpecReport

func CurrentGinkgoTestDescription deprecated 

func CurrentGinkgoTestDescription() DeprecatedGinkgoTestDescription

Deprecated: CurrentGinkgoTestDescription has been replaced with CurrentSpecReport.

Use CurrentSpecReport() instead. You can learn more here: https://onsi.github.io/ginkgo/#getting-a-report-for-the-current-spec The SpecReport type is documented here: https://pkg.go.dev/github.com/onsi/ginkgo/v2/types#SpecReport

type Done deprecated 

type Done = internal.Done

Deprecated: Done Channel for asynchronous testing

The Done channel pattern is no longer supported in Ginkgo 2.0. See here for better patterns for asynchronouse testing: https://onsi.github.io/ginkgo/#patterns-for-asynchronous-testing

For a migration guide see: https://onsi.github.io/ginkgo/MIGRATING_TO_V2#removed-async-testing

type EntryDescription 

type EntryDescription string

The EntryDescription decorator allows you to pass a format string to DescribeTable() and Entry(). This format string is used to generate entry names via: 

fmt.Sprintf(formatString, parameters...)

where parameters are the parameters passed into the entry.

When passed into an Entry the EntryDescription is used to generate the name or that entry. When passed to DescribeTable, the EntryDescription is used to generate the names for any entries that have `nil` descriptions.

You can learn more about generating EntryDescriptions here: https://onsi.github.io/ginkgo/#generating-entry-descriptions

type FlakeAttempts 

type FlakeAttempts = internal.FlakeAttempts

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

You can learn more here: https://onsi.github.io/ginkgo/#repeating-spec-runs-and-managing-flaky-specs You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

type GinkgoTInterface 

type GinkgoTInterface interface {
	Cleanup(func())
	Setenv(kev, value string)
	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

GinkgoT() implements an interface analogous to *testing.T and can be used with third-party libraries that accept *testing.T through an interface.

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

You can learn more here: https://onsi.github.io/ginkgo/#using-third-party-libraries

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

The interface implemented by GinkgoWriter 

var GinkgoWriter GinkgoWriterInterface

GinkgoWriter implements a GinkgoWriterInterface and io.Writer

When running in verbose mode (ginkgo -v) 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 and allows you to tee to a custom writer via GinkgoWriter.TeeTo(writer). Writes to GinkgoWriter are immediately sent to any registered TeeTo() writers. You can unregister all TeeTo() Writers with GinkgoWriter.ClearTeeWriters()

You can learn more at https://onsi.github.io/ginkgo/#logging-output

type Labels 

type Labels = internal.Labels

Labels are the type for spec Label decorators. Use Label(...) to construct Labels. You can learn more here: https://onsi.github.io/ginkgo/#spec-labels

func Label 

func Label(labels ...string) Labels

Label decorates specs with Labels. Multiple labels can be passed to Label and these can be arbitrary strings but must not include the following characters: "&|!,()/". Labels can be applied to container and subject nodes, but not setup nodes. You can provide multiple Labels to a given node and a spec's labels is the union of all labels in its node hierarchy.

You can learn more here: https://onsi.github.io/ginkgo/#spec-labels You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

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.

You can learn more here: https://onsi.github.io/ginkgo/#the-offset-decorator You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference

type Report 

type Report = types.Report

Report represents the report for a Suite. It is documented here: https://pkg.go.dev/github.com/onsi/ginkgo/v2/types#Report

type ReportEntryVisibility 

type ReportEntryVisibility = types.ReportEntryVisibility
ReportEntryVisibility governs the visibility of ReportEntries in Ginkgo's console reporter

- ReportEntryVisibilityAlways: the default behavior - the ReportEntry is always emitted. - ReportEntryVisibilityFailureOrVerbose: the ReportEntry is only emitted if the spec fails or if the tests are run with -v (similar to GinkgoWriters behavior). - ReportEntryVisibilityNever: the ReportEntry is never emitted though it appears in any generated machine-readable reports (e.g. by setting `--json-report`).

You can learn more about Report Entries here: https://onsi.github.io/ginkgo/#attaching-data-to-reports

type Reporter deprecated 

type Reporter = reporters.DeprecatedReporter

Deprecated: Custom Ginkgo test reporters are deprecated in Ginkgo 2.0.

Use Ginkgo's reporting nodes instead and 2.0 reporting infrastructure instead. You can learn more here: https://onsi.github.io/ginkgo/#reporting-infrastructure For a migration guide see: https://onsi.github.io/ginkgo/MIGRATING_TO_V2#removed-custom-reporters

type SpecReport 

type SpecReport = types.SpecReport

Report represents the report for a Spec. It is documented here: https://pkg.go.dev/github.com/onsi/ginkgo/v2/types#SpecReport

func CurrentSpecReport 

func CurrentSpecReport() SpecReport

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

You can learn more about SpecReport here: https://pkg.go.dev/github.com/onsi/ginkgo/types#SpecReport You can learn more about CurrentSpecReport() here: https://onsi.github.io/ginkgo/#getting-a-report-for-the-current-spec

type TableEntry 

type TableEntry struct {
	// contains filtered or unexported fields
}

TableEntry represents an entry in a table test. You generally use the `Entry` constructor.

func Entry 

func Entry(description interface{}, args ...interface{}) TableEntry

Entry constructs a TableEntry.

The first argument is a description. This can be a string, a function that accepts the parameters passed to the TableEntry and returns a string, an EntryDescription format string, or nil. If nil is provided then the name of the Entry is derived using the table-level entry description. Subsequent arguments accept any Ginkgo decorators. These are filtered out and the remaining arguments are passed into the Spec function associated with the table.

Each Entry ends up generating an individual Ginkgo It. The body of the it is the Table Body function with the Entry parameters passed in.

You can learn more about Entry here: https://onsi.github.io/ginkgo/#table-specs

func FEntry 

func FEntry(description interface{}, args ...interface{}) TableEntry

You can focus a particular entry with FEntry. This is equivalent to FIt.

func PEntry 

func PEntry(description interface{}, args ...interface{}) TableEntry

You can mark a particular entry as pending with PEntry. This is equivalent to PIt.

Source Files

View all Source files

Directories

Path Synopsis
example
books
extensions
globals
Package `globals` provides an interface to alter the global state of ginkgo suite.
 Package `globals` provides an interface to alter the global state of ginkgo suite.
table
build
command
generators
internal
labels
outline
run
unfocus
watch
_fixtures/after_run_hook_fixture
_fixtures/combined_coverage_fixture/first_package
_fixtures/combined_coverage_fixture/first_package/external_coverage
_fixtures/combined_coverage_fixture/second_package
_fixtures/coverage_fixture
_fixtures/coverage_fixture/external_coverage
_fixtures/failing_ginkgo_tests_fixture
_fixtures/flags_fixture
_fixtures/interceptor_fixture
_fixtures/labels_fixture
_fixtures/labels_fixture/onepkg
_fixtures/more_ginkgo_tests_fixture
_fixtures/no_tagged_tests_fixture
_fixtures/no_test_fn_fixture
_fixtures/no_tests_fixture
_fixtures/passing_ginkgo_tests_fixture
_fixtures/profile_fixture/block_contest
_fixtures/profile_fixture/lock_contest
_fixtures/profile_fixture/slow_memory_hog
_fixtures/watch_fixture/A
_fixtures/watch_fixture/B
_fixtures/watch_fixture/C
_fixtures/watch_fixture/D
_fixtures/xunit_fixture
global
interrupt_handler
parallel_support
test_helpers
testingtproxy
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.