The Ginkgo CLI
The Ginkgo CLI is fully documented [here](http://onsi.github.io/ginkgo/#the_ginkgo_cli)
You can also learn more by running:
Here are some of the more commonly used commands:
go install github.com/onsi/ginkgo/ginkgo
To run tests:
To run tests in all subdirectories:
To run tests in particular packages:
ginkgo <flags> /path/to/package /path/to/another/package
To pass arguments/flags to your tests:
ginkgo <flags> <packages> -- <pass-throughs>
To run tests in parallel
this will automatically detect the optimal number of nodes to use. Alternatively, you can specify the number of nodes with:
(note that you don't need to provide -p in this case).
By default the Ginkgo CLI will spin up a server that the individual test processes send test output to. The CLI aggregates this output and then presents coherent test output, one test at a time, as each test completes. An alternative is to have the parallel nodes run and stream interleaved output back. This useful for debugging, particularly in contexts where tests hang/fail to start. To get this interleaved output:
ginkgo -nodes=N -stream=true
On windows, the default value for stream is true.
By default, when running multiple tests (with -r or a list of packages) Ginkgo will abort when a test fails. To have Ginkgo run subsequent test suites instead you can:
To monitor packages and rerun tests when changes occur:
ginkgo watch <-r> </path/to/package>
passing `ginkgo watch` the `-r` flag will recursively detect all test suites under the current directory and monitor them. `watch` does not detect *new* packages. Moreover, changes in package X only rerun the tests for package X, tests for packages that depend on X are not rerun.
[OSX & Linux only] To receive (desktop) notifications when a test run completes:
this is particularly useful with `ginkgo watch`. Notifications are currently only supported on OS X and require that you `brew install terminal-notifier`
Sometimes (to suss out race conditions/flakey tests, for example) you want to keep running a test suite until it fails. You can do this with:
To bootstrap a test suite:
To generate a test file:
ginkgo generate <test_file_name>
To bootstrap/generate test files without using "." imports:
ginkgo bootstrap --nodot ginkgo generate --nodot
this will explicitly export all the identifiers in Ginkgo and Gomega allowing you to rename them to avoid collisions. When you pull to the latest Ginkgo/Gomega you'll want to run
to refresh this list and pull in any new identifiers. In particular, this will pull in any new Gomega matchers that get added.
To convert an existing XUnit style test suite to a Ginkgo-style test suite:
ginkgo convert .
To unfocus tests:
To compile a test suite:
ginkgo build <path-to-package>
will output an executable file named `package.test`. This can be run directly or by invoking
To print out Ginkgo's version:
To get more help: