Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
correcting some typos (#1064)
  • Loading branch information
felipe88alves committed Oct 20, 2022
1 parent 047c02f commit 1403d3c
Showing 1 changed file with 14 additions and 14 deletions.
28 changes: 14 additions & 14 deletions docs/index.md
Expand Up @@ -2538,7 +2538,7 @@ These Progress Reports can also show you a preview of the running source code, b

Finally - you can instruct Ginkgo to provide these Progress Reports automatically whenever a node takes too long to complete. You do this by passing the `--poll-progress-after=INTERVAL` flag to specify how long Ginkgo should wait before emitting a progress report. Once this interval is passed Ginkgo can periodically emit Progress Reports - the interval between these reports is controlled via the `--poll-progress-interval=INTERVAL` flag. By default `--poll-progress-after` is set to `0` and so Ginkgo does not emit Progress Reports.

You can ovveride the global setting of `poll-progess-after` and `poll-progress-interval` on a per-node basis by using the `PollProgressAfter(INTERVAL)` and `PollProgressInterval(INTERVAL)` decorators. A value of `0` will explicitly turn off Progress Reports for a given node regardless of the global setting.
You can override the global setting of `poll-progess-after` and `poll-progress-interval` on a per-node basis by using the `PollProgressAfter(INTERVAL)` and `PollProgressInterval(INTERVAL)` decorators. A value of `0` will explicitly turn off Progress Reports for a given node regardless of the global setting.

All Progress Reports generated by Ginkgo - whether interactively via `SIGINFO/SIGUSR1` or automatically via the `PollProgressAfter` configuration - also appear in Ginkgo's [machine-readable reports](#generating-machine-readable-reports).

Expand Down Expand Up @@ -2588,9 +2588,9 @@ It("likes to sleep in", func(ctx context.Context) {
}, NodeTimeout(time.Second))
```

rather than hang for an hour, this spec will exit (and be marked as failed due to a timeout), soon after the one second NodeTimeout deadline elapses. When the deadline elapses Ginkgo takes a [Progress Report](#getting-visibility-into-long-running-specs) snapshot to document where, exactly, the goroutine was stuck when the timeout occured. Because it is important to take the snapshot just before the context is cancelled, Ginkgo manages the timing of the cancellation directly and does not rely on a `context.WithDeadline()`-flavored context. As a result calling `ctx.Deadline()` will not return the deadline of the node in question - however you can trust that `ctx.Done()` will be closed on time.
rather than hang for an hour, this spec will exit (and be marked as failed due to a timeout), soon after the one second NodeTimeout deadline elapses. When the deadline elapses Ginkgo takes a [Progress Report](#getting-visibility-into-long-running-specs) snapshot to document where, exactly, the goroutine was stuck when the timeout occurred. Because it is important to take the snapshot just before the context is cancelled, Ginkgo manages the timing of the cancellation directly and does not rely on a `context.WithDeadline()`-flavored context. As a result calling `ctx.Deadline()` will not return the deadline of the node in question - however you can trust that `ctx.Done()` will be closed on time.

Note that you are allowed to pass in either `SpecContext` or the more canonical `context.Context` as shown in this example. The `SpecContext` object has a few additional methods attached to it and serves as an extension point for third-party libraries (including Gomega). You are free to wrap `SpecContext` however you wish (e.g. via `context.WithValue(ctx, "key", "value")`) - Ginkgo will continue to cancel the resulting context at the correct time and third-party libraries will still have access to the full-blown `SpecContext` object as it is stored as a value wihtin the context with the `"GINKGO_SPEC_CONTEXT"` key.
Note that you are allowed to pass in either `SpecContext` or the more canonical `context.Context` as shown in this example. The `SpecContext` object has a few additional methods attached to it and serves as an extension point for third-party libraries (including Gomega). You are free to wrap `SpecContext` however you wish (e.g. via `context.WithValue(ctx, "key", "value")`) - Ginkgo will continue to cancel the resulting context at the correct time and third-party libraries will still have access to the full-blown `SpecContext` object as it is stored as a value within the context with the `"GINKGO_SPEC_CONTEXT"` key.

#### The SpecTimeout and NodeTimeout Decorators

Expand Down Expand Up @@ -2632,7 +2632,7 @@ Currently, `SpecTimeout` and `NodeTimeout` cannot be applied to container nodes.

Interruptible nodes and the `SpecTimeout`/`NodeTimeout` decorators allow you to enforce deadlines at a granular per-spec/per-node level. But what happens when a node fails to return after its `SpecContext` is cancelled. What happens if it's _really_ stuck?

When a node times out Ginkgo cancels its `SpecContext` and then waits for it to exit for a period of time called the **Grace Period**. If the node exits within the Grace Period Ginkgo will continue with the relevant portions of the spec (specifically, Ginkgo will behave as if a failure occurred and skip any subsequent setup or subject nodes and, isntead, simply run through the cleanup nodes). If, however, the node does not exit within the Grace Period, Ginkgo will allow the node to _leak_ and proceed with the relevant portion of the spec.
When a node times out Ginkgo cancels its `SpecContext` and then waits for it to exit for a period of time called the **Grace Period**. If the node exits within the Grace Period Ginkgo will continue with the relevant portions of the spec (specifically, Ginkgo will behave as if a failure occurred and skip any subsequent setup or subject nodes and, instead, simply run through the cleanup nodes). If, however, the node does not exit within the Grace Period, Ginkgo will allow the node to _leak_ and proceed with the relevant portion of the spec.

A leaked node continues to run in the background - and this can, potentially, be a source of confusion for future specs as a leaked node can interact with Ginkgo's global callbacks (e.g. `Fail`, or `AddReportEntry`) and pollute the currently running spec. For this reason it's important to write specs that respond to cancelled contexts and exit as soon as possible. Nonetheless, Ginkgo takes the opinion that it is better to potentially leak a node and continue with the suite than to allow the suite to hang forever. When a node is leaked due to a timeout and elapsed Grace Period Ginkgo will emit a message stating that the node has leaked along with a [Progress Report](#getting-visibility-into-long-running-specs) that shows the currently running code in the leaked goroutine.

Expand Down Expand Up @@ -2816,9 +2816,9 @@ SynchronizedAfterSuite(func(ctx SpecContext) {
})
```

Note that the `SynchronizedAfterSuite` takes two functions - the first runs on all processes, the second only on proccess 1. Each of these can be optionally passed a context, making them independently interruptible (or not, if no context is passed in).
Note that the `SynchronizedAfterSuite` takes two functions - the first runs on all processes, the second only on process 1. Each of these can be optionally passed a context, making them independently interruptible (or not, if no context is passed in).

`SynchronizedBeforeSuite` also support indepdenently interruptible functions. [Recall](#parallel-suite-setup-and-cleanup-synchronizedbeforesuite-and-synchronizedaftersuite) that the two callbacks associated with `SynchronizedBeforeSuite` can optionally return and receive a `[]byte` array to facilitate communication between the primary process annd the other parallel processes. This optionality expands the set of possible interruptible signatures. For example:
`SynchronizedBeforeSuite` also support independently interruptible functions. [Recall](#parallel-suite-setup-and-cleanup-synchronizedbeforesuite-and-synchronizedaftersuite) that the two callbacks associated with `SynchronizedBeforeSuite` can optionally return and receive a `[]byte` array to facilitate communication between the primary process and the other parallel processes. This optionality expands the set of possible interruptible signatures. For example:

```go
SynchronizedBeforeSuite(func(ctx SpecContext) {
Expand All @@ -2835,9 +2835,9 @@ SynchronizedBeforeSuite(func(ctx SpecContext) []byte {
```
are all valid interruptible signatures. Of course you can specify `context.Context` instead and can mix-and-match interruptibility between the two functions.

Currently the **Reporting** nodes (`ReportAfterEach`, `RepoertAfterSuite`, and `ReportBeforeEach`) cannot be made interruptible and do not accept callbacks that recieve a `SpecContext`. This may change in a future release of Ginkgo (in a backward compatible way).
Currently the **Reporting** nodes (`ReportAfterEach`, `RepoertAfterSuite`, and `ReportBeforeEach`) cannot be made interruptible and do not accept callbacks that receive a `SpecContext`. This may change in a future release of Ginkgo (in a backward compatible way).

As for **Container** nodes, since these run during the Tree Construction Phase they cannot be made interruptible and so do not accept functions that expect a context. And since the `By` annotation is simply synctactic sugar enabling more detailed spec documentation, any callbacks passed to `By` cannot be independently marked as interruptible (you should, instead, use the `context` passed into the node that you're calling `By` from).
As for **Container** nodes, since these run during the Tree Construction Phase they cannot be made interruptible and so do not accept functions that expect a context. And since the `By` annotation is simply syntactic sugar enabling more detailed spec documentation, any callbacks passed to `By` cannot be independently marked as interruptible (you should, instead, use the `context` passed into the node that you're calling `By` from).

Finally, there *are* two other Ginkgo constructs that can be made interruptible and their flexibility warrants some specific coverage in this section: `DeferCleanup` and `DescribeTable`.

Expand Down Expand Up @@ -2881,7 +2881,7 @@ Describe("interacting with the library", func() {

however we've committed a subtle error. We've captured the `BeforeEach` `SpecContext` and passed it in to the `DeferCleanup` function. However the `DeferCleanup` function will only run _after_ the `BeforeEach` completes (and its `SpecContext` has been cancelled) - as a result `libraryClient.Cleanup` will always receive a cancelled context.

Morever, we want to preserve the fact that our `BeforeEach` has a 500ms timeout whereas our clean up code has a separate 1 second timeout.
Moreover, we want to preserve the fact that our `BeforeEach` has a 500ms timeout whereas our clean up code has a separate 1 second timeout.

The correct way to write this is to make the `DeferCleanup` node interruptible and decorate it with its own `NodeTimeout`:

Expand Down Expand Up @@ -2973,7 +2973,7 @@ DescribeTable("contrived context-value example",

#### SpecContext and Progress Reports

`SpecContext` provides an extension point that enables consumers to attach additional information to Progress Reports that Ginkgo generates. This is accomplished by calling `ctx.AttachProgressReporter(f)` where `f` has the signature `func() string`. Once attached, the function will be called whenever a Progress Report needs to be generated (e.g. due to a user request via `SIGINFO`/`SIGUSR1` or via an interrupt or timeout). `ctx.AttachProgressReporter` returns a detach function with signature `func()` that can be called to detach the attached progress reporter. Becuase these progress reporters are attached to the passed-in `SpecContext` they only remain attached for the lifecycle of the context: i.e. the current node.
`SpecContext` provides an extension point that enables consumers to attach additional information to Progress Reports that Ginkgo generates. This is accomplished by calling `ctx.AttachProgressReporter(f)` where `f` has the signature `func() string`. Once attached, the function will be called whenever a Progress Report needs to be generated (e.g. due to a user request via `SIGINFO`/`SIGUSR1` or via an interrupt or timeout). `ctx.AttachProgressReporter` returns a detach function with signature `func()` that can be called to detach the attached progress reporter. Because these progress reporters are attached to the passed-in `SpecContext` they only remain attached for the lifecycle of the context: i.e. the current node.

While users of Ginkgo can provide their own custom progress reporters the intent behind this extension point is to allow deeper integration between Ginkgo and third-party libraries, specifically Gomega. Whenever Gomega's `Eventually` is passed a `SpecContext` it automatically registers a progress reporter. This reporter will provide the latest state of the `Eventually` matcher - enabling users to get insight into where and why an `Eventually` might be stuck simply by asking for a Progress Report.
Expand Down Expand Up @@ -3367,7 +3367,7 @@ When running in CI you must make sure that the version of the `ginkgo` CLI you a

`go run github.com/onsi/ginkgo/v2/ginkgo`

This alone, however, is often not enough. The Ginkgo CLi includes additional dependencies that aren't part of the Ginkgo library - since your code doesn't import the cli these dependencies probably aren't in your `go.sum` file. To get around this it is idiomatic Go to introduce a `tools.go` file. This can go anywhere in your module - for example, Gomega places its `tools.go` at the top-level. Your `tools.go` file should look like:
This alone, however, is often not enough. The Ginkgo CLI includes additional dependencies that aren't part of the Ginkgo library - since your code doesn't import the cli these dependencies probably aren't in your `go.sum` file. To get around this it is idiomatic Go to introduce a `tools.go` file. This can go anywhere in your module - for example, Gomega places its `tools.go` at the top-level. Your `tools.go` file should look like:

```go
//go:build tools
Expand Down Expand Up @@ -3563,7 +3563,7 @@ var _ = Describe(describeName, func() {
...
```

Counterintuitively, this will always yield `"Smoketests - "`. The reason is that `fmt.Sprintf` is being called as go is traversing the top-level identifiers in the suite. At this point, `init` functions are being _defined_ but have not yet been invoked. So (a) we haven't actually registered our flags yet and, more importantly, (b) `go test` hasn't _parsed_ the flags yet. Our `smokeEnv` variable is therefore empty. There's no way around this - in general you should avoid trying to access configuration information at the top-level. However, if you must then you will need to use use environment variables instead of flags.
Counter-intuitively, this will always yield `"Smoketests - "`. The reason is that `fmt.Sprintf` is being called as go is traversing the top-level identifiers in the suite. At this point, `init` functions are being _defined_ but have not yet been invoked. So (a) we haven't actually registered our flags yet and, more importantly, (b) `go test` hasn't _parsed_ the flags yet. Our `smokeEnv` variable is therefore empty. There's no way around this - in general you should avoid trying to access configuration information at the top-level. However, if you must then you will need to use use environment variables instead of flags.

#### Overriding Ginkgo's command-line configuration in the suite

Expand Down Expand Up @@ -4892,9 +4892,9 @@ Both of these decorators can only be used on subject and setup nodes, not contai
#### The SpecTimeout, NodeTimeout, and GracePeriod Decorators
As described in the [Spec Timeouts and Interruptible Nodes](#spec-timeouts-and-interruptible-nodes) section, Ginkgo allows you to decorate interruptible ndoes with individual `NodeTimeout`s and spec-wide `SpecTimeout`s. `NodeTimeout` takes a `time.Duration` and applies to any interruptible node (i.e. a node with a function that accepts a `SpecContext`). `SpecTimeout` alos takes a `time.Duration` but applies only to `It` subject nodes. Whereas `NodeTimeout` specified a deadline for an individual node, `SpecTimeout` specifies a deadline for all nodes associated with an individual spec.
As described in the [Spec Timeouts and Interruptible Nodes](#spec-timeouts-and-interruptible-nodes) section, Ginkgo allows you to decorate interruptible nodes with individual `NodeTimeout`s and spec-wide `SpecTimeout`s. `NodeTimeout` takes a `time.Duration` and applies to any interruptible node (i.e. a node with a function that accepts a `SpecContext`). `SpecTimeout` also takes a `time.Duration` but applies only to `It` subject nodes. Whereas `NodeTimeout` specified a deadline for an individual node, `SpecTimeout` specifies a deadline for all nodes associated with an individual spec.
Once interrupted, Ginkgo waits for a Grace Period before abanding a node and moving on. A global Grace Period can be specified via the `--grace-period=DURATION` cli flag and overrideen by the `GracePeriod` decorator on a per-node basis. `GracePeriod` takes a `time.Duration` and can only be applied to interruptible nodes.
Once interrupted, Ginkgo waits for a Grace Period before abandoning a node and moving on. A global Grace Period can be specified via the `--grace-period=DURATION` cli flag and overridden by the `GracePeriod` decorator on a per-node basis. `GracePeriod` takes a `time.Duration` and can only be applied to interruptible nodes.
Currently none of these decorators can be applied to container nodes.
Expand Down

0 comments on commit 1403d3c

Please sign in to comment.