118 lines
6.8 KiB
Markdown
118 lines
6.8 KiB
Markdown
|
|
||
|
|
|
||
|
|
[](https://travis-ci.org/onsi/ginkgo)
|
||
|
|
|
||
|
|
Jump to the [docs](http://onsi.github.io/ginkgo/) to learn more. To start rolling your Ginkgo tests *now* [keep reading](#set-me-up)!
|
||
|
|
|
||
|
|
If you have a question, comment, bug report, feature request, etc. please open a GitHub issue.
|
||
|
|
|
||
|
|
## Feature List
|
||
|
|
|
||
|
|
- Ginkgo uses Go's `testing` package and can live alongside your existing `testing` tests. It's easy to [bootstrap](http://onsi.github.io/ginkgo/#bootstrapping-a-suite) and start writing your [first tests](http://onsi.github.io/ginkgo/#adding-specs-to-a-suite)
|
||
|
|
|
||
|
|
- Structure your BDD-style tests expressively:
|
||
|
|
- Nestable [`Describe` and `Context` container blocks](http://onsi.github.io/ginkgo/#organizing-specs-with-containers-describe-and-context)
|
||
|
|
- [`BeforeEach` and `AfterEach` blocks](http://onsi.github.io/ginkgo/#extracting-common-setup-beforeeach) for setup and teardown
|
||
|
|
- [`It` blocks](http://onsi.github.io/ginkgo/#individual-specs-) that hold your assertions
|
||
|
|
- [`JustBeforeEach` blocks](http://onsi.github.io/ginkgo/#separating-creation-and-configuration-justbeforeeach) that separate creation from configuration (also known as the subject action pattern).
|
||
|
|
- [`BeforeSuite` and `AfterSuite` blocks](http://onsi.github.io/ginkgo/#global-setup-and-teardown-beforesuite-and-aftersuite) to prep for and cleanup after a suite.
|
||
|
|
|
||
|
|
- A comprehensive test runner that lets you:
|
||
|
|
- Mark specs as [pending](http://onsi.github.io/ginkgo/#pending-specs)
|
||
|
|
- [Focus](http://onsi.github.io/ginkgo/#focused-specs) individual specs, and groups of specs, either programmatically or on the command line
|
||
|
|
- Run your tests in [random order](http://onsi.github.io/ginkgo/#spec-permutation), and then reuse random seeds to replicate the same order.
|
||
|
|
- Break up your test suite into parallel processes for straightforward [test parallelization](http://onsi.github.io/ginkgo/#parallel-specs)
|
||
|
|
|
||
|
|
- `ginkgo`: a command line interface with plenty of handy command line arguments for [running your tests](http://onsi.github.io/ginkgo/#running-tests) and [generating](http://onsi.github.io/ginkgo/#generators) test files. Here are a few choice examples:
|
||
|
|
- `ginkgo -nodes=N` runs your tests in `N` parallel processes and print out coherent output in realtime
|
||
|
|
- `ginkgo -cover` runs your tests using Golang's code coverage tool
|
||
|
|
- `ginkgo convert` converts an XUnit-style `testing` package to a Ginkgo-style package
|
||
|
|
- `ginkgo -focus="REGEXP"` and `ginkgo -skip="REGEXP"` allow you to specify a subset of tests to run via regular expression
|
||
|
|
- `ginkgo -r` runs all tests suites under the current directory
|
||
|
|
- `ginkgo -v` prints out identifying information for each tests just before it runs
|
||
|
|
|
||
|
|
And much more: run `ginkgo help` for details!
|
||
|
|
|
||
|
|
The `ginkgo` CLI is convenient, but purely optional -- Ginkgo works just fine with `go test`
|
||
|
|
|
||
|
|
- `ginkgo watch` [watches](https://onsi.github.io/ginkgo/#watching-for-changes) packages *and their dependencies* for changes, then reruns tests. Run tests immediately as you develop!
|
||
|
|
|
||
|
|
- Built-in support for testing [asynchronicity](http://onsi.github.io/ginkgo/#asynchronous-tests)
|
||
|
|
|
||
|
|
- Built-in support for [benchmarking](http://onsi.github.io/ginkgo/#benchmark-tests) your code. Control the number of benchmark samples as you gather runtimes and other, arbitrary, bits of numerical information about your code.
|
||
|
|
|
||
|
|
- [Completions for Sublime Text](https://github.com/onsi/ginkgo-sublime-completions): just use [Package Control](https://sublime.wbond.net/) to install `Ginkgo Completions`.
|
||
|
|
|
||
|
|
- [Completions for VSCode](https://github.com/onsi/vscode-ginkgo): just use VSCode's extension installer to install `vscode-ginkgo`.
|
||
|
|
|
||
|
|
- Straightforward support for third-party testing libraries such as [Gomock](https://code.google.com/p/gomock/) and [Testify](https://github.com/stretchr/testify). Check out the [docs](http://onsi.github.io/ginkgo/#third-party-integrations) for details.
|
||
|
|
|
||
|
|
- A modular architecture that lets you easily:
|
||
|
|
- Write [custom reporters](http://onsi.github.io/ginkgo/#writing-custom-reporters) (for example, Ginkgo comes with a [JUnit XML reporter](http://onsi.github.io/ginkgo/#generating-junit-xml-output) and a TeamCity reporter).
|
||
|
|
- [Adapt an existing matcher library (or write your own!)](http://onsi.github.io/ginkgo/#using-other-matcher-libraries) to work with Ginkgo
|
||
|
|
|
||
|
|
## [Gomega](http://github.com/onsi/gomega): Ginkgo's Preferred Matcher Library
|
||
|
|
|
||
|
|
Ginkgo is best paired with Gomega. Learn more about Gomega [here](http://onsi.github.io/gomega/)
|
||
|
|
|
||
|
|
## [Agouti](http://github.com/sclevine/agouti): A Golang Acceptance Testing Framework
|
||
|
|
|
||
|
|
Agouti allows you run WebDriver integration tests. Learn more about Agouti [here](http://agouti.org)
|
||
|
|
|
||
|
|
## Set Me Up!
|
||
|
|
|
||
|
|
You'll need Golang v1.3+ (Ubuntu users: you probably have Golang v1.0 -- you'll need to upgrade!)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
|
||
|
|
go get github.com/onsi/ginkgo/ginkgo # installs the ginkgo CLI
|
||
|
|
go get github.com/onsi/gomega # fetches the matcher library
|
||
|
|
|
||
|
|
cd path/to/package/you/want/to/test
|
||
|
|
|
||
|
|
ginkgo bootstrap # set up a new ginkgo suite
|
||
|
|
ginkgo generate # will create a sample test file. edit this file and add your tests then...
|
||
|
|
|
||
|
|
go test # to run your tests
|
||
|
|
|
||
|
|
ginkgo # also runs your tests
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
## I'm new to Go: What are my testing options?
|
||
|
|
|
||
|
|
Of course, I heartily recommend [Ginkgo](https://github.com/onsi/ginkgo) and [Gomega](https://github.com/onsi/gomega). Both packages are seeing heavy, daily, production use on a number of projects and boast a mature and comprehensive feature-set.
|
||
|
|
|
||
|
|
With that said, it's great to know what your options are :)
|
||
|
|
|
||
|
|
### What Golang gives you out of the box
|
||
|
|
|
||
|
|
Testing is a first class citizen in Golang, however Go's built-in testing primitives are somewhat limited: The [testing](http://golang.org/pkg/testing) package provides basic XUnit style tests and no assertion library.
|
||
|
|
|
||
|
|
### Matcher libraries for Golang's XUnit style tests
|
||
|
|
|
||
|
|
A number of matcher libraries have been written to augment Go's built-in XUnit style tests. Here are two that have gained traction:
|
||
|
|
|
||
|
|
- [testify](https://github.com/stretchr/testify)
|
||
|
|
- [gocheck](http://labix.org/gocheck)
|
||
|
|
|
||
|
|
You can also use Ginkgo's matcher library [Gomega](https://github.com/onsi/gomega) in [XUnit style tests](http://onsi.github.io/gomega/#using-gomega-with-golangs-xunitstyle-tests)
|
||
|
|
|
||
|
|
### BDD style testing frameworks
|
||
|
|
|
||
|
|
There are a handful of BDD-style testing frameworks written for Golang. Here are a few:
|
||
|
|
|
||
|
|
- [Ginkgo](https://github.com/onsi/ginkgo) ;)
|
||
|
|
- [GoConvey](https://github.com/smartystreets/goconvey)
|
||
|
|
- [Goblin](https://github.com/franela/goblin)
|
||
|
|
- [Mao](https://github.com/azer/mao)
|
||
|
|
- [Zen](https://github.com/pranavraja/zen)
|
||
|
|
|
||
|
|
Finally, @shageman has [put together](https://github.com/shageman/gotestit) a comprehensive comparison of golang testing libraries.
|
||
|
|
|
||
|
|
Go explore!
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
Ginkgo is MIT-Licensed
|