ContinueOnFailure is a decorator that allows you to mark an Ordered container to continue running specs even if failures occur. Ordinarily an ordered container will stop running specs after the first failure occurs. Note that if a BeforeAll or a BeforeEach/JustBeforeEach annotated with OncePerOrdered fails then no specs will run as the precondition for the Ordered container will consider to be failed.
ContinueOnFailure only applies to the outermost Ordered container. Attempting to place ContinueOnFailure in a nested container will result in an error.
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
const ContinueOnFailure = internal.ContinueOnFailure
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
const Focus = internal.Focus
const GINKGO_VERSION = types.VERSION
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 learn 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
const OncePerOrdered = internal.OncePerOrdered
Ordered is a decorator that allows you to mark a container as ordered. Specs 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
const Ordered = internal.Ordered
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
const Pending = internal.Pending
const ReportEntryVisibilityAlways, ReportEntryVisibilityFailureOrVerbose, ReportEntryVisibilityNever = types.ReportEntryVisibilityAlways, types.ReportEntryVisibilityFailureOrVerbose, types.ReportEntryVisibilityNever
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. Specs 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
const Serial = internal.Serial
SuppressProgressReporting is a decorator that allows you to disable progress reporting of a particular node. This is useful if `ginkgo -v -progress` is generating too much noise; particularly if you have a `ReportAfterEach` node that is running for every skipped spec and is generating lots of progress reports.
const SuppressProgressReporting = internal.SuppressProgressReporting
Context is an alias for Describe - it generates the exact same kind of Container node
var Context, FContext, PContext, XContext = Describe, FDescribe, PDescribe, XDescribe
GinkgoLogr is a logr.Logger that writes to GinkgoWriter
var GinkgoLogr logr.Logger
Specify is an alias for It - it can allow for more natural wording in some context.
var Specify, FSpecify, PSpecify, XSpecify = It, FIt, PIt, XIt
XDescribe marks specs within the Describe block as pending.
XDescribe is an alias for PDescribe
var XDescribe = PDescribe
You can mark a table as pending with `XDescribeTable`. This is equivalent to `XDescribe`.
var XDescribeTable = PDescribeTable
You can mark a table as pending with `XDescribeTableSubtree`. This is equivalent to `XDescribe`.
var XDescribeTableSubtree = PDescribeTableSubtree
You can mark a particular entry as pending with XEntry. This is equivalent to XIt.
var XEntry = PEntry
XIt allows you to mark an individual It as pending.
XIt is an alias for PIt
var XIt = PIt
var XWhen = PWhen
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(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:
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(args ...interface{}) bool
AfterAll nodes are Setup nodes that can occur inside Ordered containers. 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.
AfterAll can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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(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.
AfterEach can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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(body interface{}, args ...interface{}) 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.
AfterSuite can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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 AttachProgressReporter(reporter func() string) func()
AttachProgressReporter allows you to register a function that will be called whenever Ginkgo generates a Progress Report. The contents returned by the function will be included in the report.
**This is an experimental feature and the public-facing interface may change in a future minor version of Ginkgo**
Progress Reports are generated: - whenever the user explicitly requests one (via `SIGINFO` or `SIGUSR1`) - on nodes decorated with PollProgressAfter - on suites run with --poll-progress-after - whenever a test times out
Ginkgo uses Progress Reports to convey the current state of the test suite, including any running goroutines. By attaching a progress reporter you are able to supplement these reports with additional information.
You can learn more about AttachProgressReporter here: https://onsi.github.io/ginkgo/#attaching-additional-information-to-progress-reports
func BeforeAll(args ...interface{}) bool
BeforeAll nodes are Setup nodes that can occur inside Ordered containers. 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.
BeforeAll can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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(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.
BeforeEach can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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(body interface{}, args ...interface{}) 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.
BeforeSuite can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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(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 syntactic sugar around GinkgoWriter and AddReportEntry You can learn more about By here: https://onsi.github.io/ginkgo/#documenting-complex-specs-by
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 multiple values. `DeferCleanup` will ignore all these return values except for the last one. If this last return value is a non-nil error `DeferCleanup` will fail the spec). 3. A function that takes a context.Context or SpecContext (and optionally returns multiple values). The resulting cleanup node is deemed interruptible and the passed-in context will be cancelled in the event of a timeout or interrupt. 4. A function that takes arguments (and optionally returns multiple values) followed by a list of arguments to pass to the function. 5. A function that takes SpecContext and a list of arguments (and optionally returns multiple values) followed by a list of arguments to pass 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 its current value (obtained by os.GetEnv("FOO")) after the spec runs and then sets the environment variable "FOO" to "BAR" for the current spec.
Similarly:
BeforeEach(func() {
DeferCleanup(func(ctx SpecContext, path) {
req, err := http.NewRequestWithContext(ctx, "POST", path, nil)
Expect(err).NotTo(HaveOccured())
_, err := http.DefaultClient.Do(req)
Expect(err).NotTo(HaveOccured())
}, "example.com/cleanup", NodeTimeout(time.Second*3))
})
will register a cleanup handler that will have three seconds to successfully complete a request to the specified path. Note that we do not specify a context in the list of arguments passed to DeferCleanup - only in the signature of the function we pass in. Ginkgo will detect the requested context and supply a SpecContext when it invokes the cleanup node. If you want to pass in your own context in addition to the Ginkgo-provided SpecContext you must specify the SpecContext as the first argument (e.g. func(ctx SpecContext, otherCtx context.Context)).
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(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(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 DescribeTableSubtree(description string, args ...interface{}) bool
DescribeTableSubtree describes a table-driven spec that generates a set of tests for each entry.
For example:
DescribeTableSubtree("a subtree table",
func(url string, code int, message string) {
var resp *http.Response
BeforeEach(func() {
var err error
resp, err = http.Get(url)
Expect(err).NotTo(HaveOccurred())
DeferCleanup(resp.Body.Close)
})
It("should return the expected status code", func() {
Expect(resp.StatusCode).To(Equal(code))
})
It("should return the expected message", func() {
body, err := ioutil.ReadAll(resp.Body)
Expect(err).NotTo(HaveOccurred())
Expect(string(body)).To(Equal(message))
})
},
Entry("default response", "example.com/response", http.StatusOK, "hello world"),
Entry("missing response", "example.com/missing", http.StatusNotFound, "wat?"),
)
Note that you **must** place define an It inside the body function.
You can learn more about DescribeTableSubtree 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(text string, args ...interface{}) bool
FDescribe focuses specs within the Describe block.
func FDescribeTable(description string, args ...interface{}) bool
You can focus a table with `FDescribeTable`. This is equivalent to `FDescribe`.
func FDescribeTableSubtree(description string, args ...interface{}) bool
You can focus a table with `FDescribeTableSubtree`. This is equivalent to `FDescribe`.
func FIt(text string, args ...interface{}) bool
FIt allows you to focus an individual It.
func FWhen(text string, args ...interface{}) bool
When is an alias for Describe - it generates the exact same kind of Container node
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() (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 programmatically 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 GinkgoHelper()
GinkgoHelper marks the function it's called in as a test helper. When a failure occurs inside a helper function, Ginkgo will skip the helper when analyzing the stack trace to identify where the failure occurred.
This is an alternative, simpler, mechanism to passing in a skip offset when calling Fail or using Gomega.
func GinkgoLabelFilter() string
GinkgoLabelFilter() returns the label filter configured for this suite via `--label-filter`.
You can use this to manually check if a set of labels would satisfy the filter via:
if (Label("cat", "dog").MatchesLabelFilter(GinkgoLabelFilter())) {
//...
}
func GinkgoParallelNode() int
Deprecated: GinkgoParallelNode() has been renamed to 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() 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()
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(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 pass It nodes bare functions (func() {}) or functions that receive a SpecContext or context.Context: func(ctx SpecContext) {} and func (ctx context.Context) {}. If the function takes a context then the It is deemed interruptible and Ginkgo will cancel the context in the event of a timeout (configured via the SpecTimeout() or NodeTimeout() decorators) or of an interrupt signal.
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(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.
JustAfterEach can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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(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.
JustBeforeEach can take a func() body, or an interruptible func(SpecContext)/func(context.Context) body.
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(_ ...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(text string, args ...interface{}) bool
PDescribe marks specs within the Describe block as pending.
func PDescribeTable(description string, args ...interface{}) bool
You can mark a table as pending with `PDescribeTable`. This is equivalent to `PDescribe`.
func PDescribeTableSubtree(description string, args ...interface{}) bool
You can mark a table as pending with `PDescribeTableSubtree`. This is equivalent to `PDescribe`.
func PIt(text string, args ...interface{}) bool
PIt allows you to mark an individual It as pending.
func PWhen(text string, args ...interface{}) bool
When is an alias for Describe - it generates the exact same kind of Container node
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(body any, args ...any) 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 or both SpecContext and Report for interruptible behavior. They are called after the spec has completed and receive the final report for the spec.
Example:
ReportAfterEach(func(report SpecReport) { // process report })
ReportAfterEach(func(ctx SpecContext, report SpecReport) {
// process report
}), NodeTimeout(1 * time.Minute))
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
You can learn about interruptible nodes here: https://onsi.github.io/ginkgo/#spec-timeouts-and-interruptible-nodes
func ReportAfterSuite(text string, body any, args ...interface{}) bool
ReportAfterSuite nodes are run at the end of the suite. ReportAfterSuite nodes execute at the suite's conclusion, and accept a function that can either receive Report or both SpecContext and Report for interruptible behavior.
Example Usage:
ReportAfterSuite("Non-interruptible ReportAfterSuite", func(r Report) { // process report })
ReportAfterSuite("Interruptible ReportAfterSuite", func(ctx SpecContext, r Report) {
// process report
}, NodeTimeout(1 * time.Minute))
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 programmatically 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
You can learn about interruptible nodes here: https://onsi.github.io/ginkgo/#spec-timeouts-and-interruptible-nodes
func ReportBeforeEach(body any, args ...any) 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 or both SpecContext and Report for interruptible behavior. They are called before the spec starts.
Example:
ReportBeforeEach(func(report SpecReport) { // process report })
ReportBeforeEach(func(ctx SpecContext, report SpecReport) {
// process report
}), NodeTimeout(1 * time.Minute))
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
You can learn about interruptible nodes here: https://onsi.github.io/ginkgo/#spec-timeouts-and-interruptible-nodes
func ReportBeforeSuite(body any, args ...any) bool
ReportBeforeSuite nodes are run at the beginning of the suite. ReportBeforeSuite nodes take a function that can either receive Report or both SpecContext and Report for interruptible behavior.
Example Usage:
ReportBeforeSuite(func(r Report) { // process report })
ReportBeforeSuite(func(ctx SpecContext, r Report) {
// process report
}, NodeTimeout(1 * time.Minute))
They are called at the beginning of the suite, before any specs have run and any BeforeSuite or SynchronizedBeforeSuite nodes, and are passed in the initial report for the suite. ReportBeforeSuite nodes must be created at the top-level (i.e. not nested in a Context/Describe/When node)
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
You can learn about interruptible nodes here: https://onsi.github.io/ginkgo/#spec-timeouts-and-interruptible-nodes
func ResumeOutputInterception()
ResumeOutputInterception() - see docs for PauseOutputInterception()
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 overridden, 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(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(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(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(allProcessBody interface{}, process1Body interface{}, args ...interface{}) 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. These two functions can be bare functions (func()) or interruptible (func(context.Context)/func(SpecContext))
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(process1Body interface{}, allProcessBody interface{}, args ...interface{}) 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) can have any of the following the signatures:
func() func(ctx context.Context) func(ctx SpecContext) func() []byte func(ctx context.Context) []byte func(ctx SpecContext) []byte
The byte array returned by the first function (if present) is then passed to the second function, which can have any of the following signature:
func() func(ctx context.Context) func(ctx SpecContext) func(data []byte) func(ctx context.Context, data []byte) func(ctx SpecContext, data []byte)
If either function receives a context.Context/SpecContext it is considered interruptible.
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
func When(text string, args ...interface{}) bool
When is an alias for Describe - it generates the exact same kind of Container node
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 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: 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
type DeprecatedGinkgoTestDescription struct {
FullTestText string
ComponentTexts []string
TestText string
FileName string
LineNumber int
Failed bool
Duration time.Duration
}
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
Deprecated: Done Channel for asynchronous testing
The Done channel pattern is no longer supported in Ginkgo 2.0. See here for better patterns for asynchronous 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 Done = internal.Done
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 EntryDescription string
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/#the-flakeattempts-decorator You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference
type FlakeAttempts = internal.FlakeAttempts
Additional methods returned by GinkgoT() that provide deeper integration points into Ginkgo
type FullGinkgoTInterface interface {
GinkgoTInterface
AddReportEntryVisibilityAlways(name string, args ...any)
AddReportEntryVisibilityFailureOrVerbose(name string, args ...any)
AddReportEntryVisibilityNever(name string, args ...any)
//Prints to the GinkgoWriter
Print(a ...any)
Printf(format string, a ...any)
Println(a ...any)
//Provides access to Ginkgo's color formatting, correctly configured to match the color settings specified in the invocation of ginkgo
F(format string, args ...any) string
Fi(indentation uint, format string, args ...any) string
Fiw(indentation uint, maxWidth uint, format string, args ...any) string
//Generates a formatted string version of the current spec's timeline
RenderTimeline() string
GinkgoRecover()
DeferCleanup(args ...any)
RandomSeed() int64
ParallelProcess() int
ParallelTotal() int
AttachProgressReporter(func() string) func()
}
func GinkgoT(optionalOffset ...int) FullGinkgoTInterface
GinkgoT() implements an interface that allows third party libraries to integrate with and build on top of Ginkgo.
GinkgoT() is analogous to *testing.T and implements the majority of *testing.T's methods. It can be typically be used a a drop-in replacement 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 - though you do not need to use this if you call GinkgoHelper() or GinkgoT().Helper() appropriately
GinkgoT() attempts to mimic the behavior of `testing.T` with the exception of the following:
- Error/Errorf: failures in Ginkgo always immediately stop execution and there is no mechanism to log a failure without aborting the test. As such Error/Errorf are equivalent to Fatal/Fatalf. - Parallel() is a no-op as Ginkgo's multi-process parallelism model is substantially different from go test's in-process model.
You can learn more here: https://onsi.github.io/ginkgo/#using-third-party-libraries
type GinkgoTBWrapper struct {
testing.TB
GinkgoT FullGinkgoTInterface
}
func GinkgoTB(optionalOffset ...int) *GinkgoTBWrapper
GinkgoTB() implements a wrapper that exactly matches the testing.TB interface.
In go 1.18 a new private() function was added to the testing.TB interface. Any function which accepts testing.TB as input needs to be passed in something that directly implements testing.TB.
This wrapper satisfies the testing.TB interface and intended to be used as a drop-in replacement with third party libraries that accept testing.TB.
Similar to GinkgoT(), GinkgoTB() takes an optional offset argument that can be used to get the correct line number associated with the failure - though you do not need to use this if you call GinkgoHelper() or GinkgoT().Helper() appropriately
func (g *GinkgoTBWrapper) Cleanup(f func())
func (g *GinkgoTBWrapper) Error(args ...any)
func (g *GinkgoTBWrapper) Errorf(format string, args ...any)
func (g *GinkgoTBWrapper) Fail()
func (g *GinkgoTBWrapper) FailNow()
func (g *GinkgoTBWrapper) Failed() bool
func (g *GinkgoTBWrapper) Fatal(args ...any)
func (g *GinkgoTBWrapper) Fatalf(format string, args ...any)
func (g *GinkgoTBWrapper) Helper()
func (g *GinkgoTBWrapper) Log(args ...any)
func (g *GinkgoTBWrapper) Logf(format string, args ...any)
func (g *GinkgoTBWrapper) Name() string
func (g *GinkgoTBWrapper) Setenv(key, value string)
func (g *GinkgoTBWrapper) Skip(args ...any)
func (g *GinkgoTBWrapper) SkipNow()
func (g *GinkgoTBWrapper) Skipf(format string, args ...any)
func (g *GinkgoTBWrapper) Skipped() bool
func (g *GinkgoTBWrapper) TempDir() string
The portion of the interface returned by GinkgoT() that maps onto methods in the testing package's T.
type GinkgoTInterface interface {
Cleanup(func())
Setenv(kev, value string)
Error(args ...any)
Errorf(format string, args ...any)
Fail()
FailNow()
Failed() bool
Fatal(args ...any)
Fatalf(format string, args ...any)
Helper()
Log(args ...any)
Logf(format string, args ...any)
Name() string
Parallel()
Skip(args ...any)
SkipNow()
Skipf(format string, args ...any)
Skipped() bool
TempDir() string
}
type GinkgoTestDescription = DeprecatedGinkgoTestDescription
The interface by which Ginkgo receives *testing.T
type GinkgoTestingT interface {
Fail()
}
The interface implemented by GinkgoWriter
type GinkgoWriterInterface interface {
io.Writer
Print(a ...interface{})
Printf(format string, a ...interface{})
Println(a ...interface{})
TeeTo(writer io.Writer)
ClearTeeWriters()
}
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
var GinkgoWriter GinkgoWriterInterface
GracePeriod denotes the period of time Ginkgo will wait for an interruptible node to exit once an interruption (whether due to a timeout or a user-invoked signal) has occurred. If both the global --grace-period cli flag and a GracePeriod decorator are specified the value in the decorator will take precedence.
Nodes that do not finish within a GracePeriod will be leaked and Ginkgo will proceed to run subsequent nodes. In the event of a timeout, such leaks will be reported to the user.
type GracePeriod = internal.GracePeriod
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
type Labels = internal.Labels
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
MustPassRepeatedly(uint N) is a decorator that allows you to repeat the execution of individual specs or spec containers. Ginkgo will run them up to `N` times until they fail.
You can learn more here: https://onsi.github.io/ginkgo/#the-mustpassrepeatedly-decorator You can learn more about decorators here: https://onsi.github.io/ginkgo/#decorator-reference
type MustPassRepeatedly = internal.MustPassRepeatedly
NodeTimeout allows you to specify a timeout for an indivdiual node. The node cannot be a container and must be interruptible (i.e. it must be passed a function that accepts a SpecContext or context.Context).
If the node does not exit within the specified NodeTimeout its context will be cancelled. The node wil then have a period of time controlled by the GracePeriod decorator (or global --grace-period command-line argument) to exit. If the node does not exit within GracePeriod Ginkgo will leak the node and proceed to any clean-up nodes associated with the current spec.
type NodeTimeout = internal.NodeTimeout
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 Offset = internal.Offset
PollProgressAfter allows you to override the configured value for --poll-progress-after for a particular node.
Ginkgo will start emitting node progress if the node is still running after a duration of PollProgressAfter. This allows you to get quicker feedback about the state of a long-running spec.
type PollProgressAfter = internal.PollProgressAfter
PollProgressInterval allows you to override the configured value for --poll-progress-interval for a particular node.
Once a node has been running for longer than PollProgressAfter Ginkgo will emit node progress periodically at an interval of PollProgresInterval.
type PollProgressInterval = internal.PollProgressInterval
Report represents the report for a Suite. It is documented here: https://pkg.go.dev/github.com/onsi/ginkgo/v2/types#Report
type Report = types.Report
func PreviewSpecs(description string, args ...any) Report
PreviewSpecs walks the testing tree and produces a report without actually invoking the specs. See http://onsi.github.io/ginkgo/#previewing-specs for more information.
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 ReportEntryVisibility = types.ReportEntryVisibility
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 Reporter = reporters.DeprecatedReporter
SpecContext is the context object passed into nodes that are subject to a timeout or need to be notified of an interrupt. It implements the standard context.Context interface but also contains additional helpers to provide an extensibility point for Ginkgo. (As an example, Gomega's Eventually can use the methods defined on SpecContext to provide deeper integration with Ginkgo).
You can do anything with SpecContext that you do with a typical context.Context including wrapping it with any of the context.With* methods.
Ginkgo will cancel the SpecContext when a node is interrupted (e.g. by the user sending an interrupt signal) or when a node has exceeded its allowed run-time. Note, however, that even in cases where a node has a deadline, SpecContext will not return a deadline via .Deadline(). This is because Ginkgo does not use a WithDeadline() context to model node deadlines as Ginkgo needs control over the precise timing of the context cancellation to ensure it can provide an accurate progress report at the moment of cancellation.
type SpecContext = internal.SpecContext
Report represents the report for a Spec. It is documented here: https://pkg.go.dev/github.com/onsi/ginkgo/v2/types#SpecReport
type SpecReport = types.SpecReport
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
SpecTimeout allows you to specify a timeout for an indivdiual spec. SpecTimeout can only decorate interruptible It nodes.
All nodes associated with the It node will need to complete before the SpecTimeout has elapsed. Individual nodes (e.g. BeforeEach) may be decorated with different NodeTimeouts - but these can only serve to provide a more stringent deadline for the node in question; they cannot extend the deadline past the SpecTimeout.
If the spec does not complete within the specified SpecTimeout the currently running node will have its context cancelled. The node wil then have a period of time controlled by that node's GracePeriod decorator (or global --grace-period command-line argument) to exit. If the node does not exit within GracePeriod Ginkgo will leak the node and proceed to any clean-up nodes associated with the current spec.
type SpecTimeout = internal.SpecTimeout
TableEntry represents an entry in a table test. You generally use the `Entry` constructor.
type TableEntry struct {
// contains filtered or unexported fields
}
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.
If you want to generate interruptible specs simply write a Table function that accepts a SpecContext as its first argument. You can then decorate individual Entrys with the NodeTimeout and SpecTimeout decorators.
You can learn more about Entry here: https://onsi.github.io/ginkgo/#table-specs
func FEntry(description interface{}, args ...interface{}) TableEntry
You can focus a particular entry with FEntry. This is equivalent to FIt.
func PEntry(description interface{}, args ...interface{}) TableEntry
You can mark a particular entry as pending with PEntry. This is equivalent to PIt.
| Name | Synopsis |
|---|---|
| .. | |
| config | |
| dsl | |
| core | Ginkgo is usually dot-imported via: |
| decorators | Ginkgo is usually dot-imported via: |
| reporting | Ginkgo is usually dot-imported via: |
| table | Ginkgo is usually dot-imported via: |
| extensions | |
| globals | Package `globals` provides an interface to alter the global state of ginkgo suite. |
| table | |
| formatter | |
| ginkgo | |
| build | |
| command | |
| generators | |
| labels | |
| outline | |
| run | |
| unfocus | |
| watch | |
| integration | |
| reporters | Ginkgo's Default Reporter |
| types | |