README.md
1
2
3[](https://travis-ci.org/onsi/ginkgo)
4[](https://github.com/onsi/ginkgo/actions?query=workflow%3Atest+branch%3Amaster)
5
6Jump to the [docs](https://onsi.github.io/ginkgo/) | [中文文档](https://ke-chain.github.io/ginkgodoc) to learn more. To start rolling your Ginkgo tests *now* [keep reading](#set-me-up)!
7
8If you have a question, comment, bug report, feature request, etc. please open a GitHub issue, or visit the [Ginkgo Slack channel](https://app.slack.com/client/T029RQSE6/CQQ50BBNW).
9
10# Ginkgo 2.0 is coming soon!
11
12An effort is underway to develop and deliver Ginkgo 2.0. The work is happening in the [v2](https://github.com/onsi/ginkgo/tree/v2) branch and a changelog and migration guide is being maintained on that branch [here](https://github.com/onsi/ginkgo/blob/v2/docs/MIGRATING_TO_V2.md). Issue [#711](https://github.com/onsi/ginkgo/issues/711) is the central place for discussion and links to the original [proposal doc](https://docs.google.com/document/d/1h28ZknXRsTLPNNiOjdHIO-F2toCzq4xoZDXbfYaBdoQ/edit#).
13
14As described in the [changelog](https://github.com/onsi/ginkgo/blob/v2/docs/MIGRATING_TO_V2.md) and [proposal](https://docs.google.com/document/d/1h28ZknXRsTLPNNiOjdHIO-F2toCzq4xoZDXbfYaBdoQ/edit#), Ginkgo 2.0 will clean up the Ginkgo codebase, deprecate and remove some v1 functionality, and add several new much-requested features. To help users get ready for the migration, Ginkgo v1 has started emitting deprecation warnings for features that will no longer be supported with links to documentation for how to migrate away from these features. If you have concerns or comments please chime in on [#711](https://github.com/onsi/ginkgo/issues/711).
15
16The current timeline for completion of 2.0 looks like:
17
18- Early April 2021: first public release of 2.0, deprecation warnings land in v1.
19- May 2021: first beta/rc of 2.0 with most new functionality in place.
20- June/July 2021: 2.0 ships and fully replaces the 1.x codebase on master.
21
22## TLDR
23Ginkgo builds on Go's `testing` package, allowing expressive [Behavior-Driven Development](https://en.wikipedia.org/wiki/Behavior-driven_development) ("BDD") style tests.
24It is typically (and optionally) paired with the [Gomega](https://github.com/onsi/gomega) matcher library.
25
26```go
27Describe("the strings package", func() {
28 Context("strings.Contains()", func() {
29 When("the string contains the substring in the middle", func() {
30 It("returns `true`", func() {
31 Expect(strings.Contains("Ginkgo is awesome", "is")).To(BeTrue())
32 })
33 })
34 })
35})
36```
37
38## Feature List
39
40- Ginkgo uses Go's `testing` package and can live alongside your existing `testing` tests. It's easy to [bootstrap](https://onsi.github.io/ginkgo/#bootstrapping-a-suite) and start writing your [first tests](https://onsi.github.io/ginkgo/#adding-specs-to-a-suite)
41
42- Ginkgo allows you to write tests in Go using expressive [Behavior-Driven Development](https://en.wikipedia.org/wiki/Behavior-driven_development) ("BDD") style:
43 - Nestable [`Describe`, `Context` and `When` container blocks](https://onsi.github.io/ginkgo/#organizing-specs-with-containers-describe-and-context)
44 - [`BeforeEach` and `AfterEach` blocks](https://onsi.github.io/ginkgo/#extracting-common-setup-beforeeach) for setup and teardown
45 - [`It` and `Specify` blocks](https://onsi.github.io/ginkgo/#individual-specs-it) that hold your assertions
46 - [`JustBeforeEach` blocks](https://onsi.github.io/ginkgo/#separating-creation-and-configuration-justbeforeeach) that separate creation from configuration (also known as the subject action pattern).
47 - [`BeforeSuite` and `AfterSuite` blocks](https://onsi.github.io/ginkgo/#global-setup-and-teardown-beforesuite-and-aftersuite) to prep for and cleanup after a suite.
48
49- A comprehensive test runner that lets you:
50 - Mark specs as [pending](https://onsi.github.io/ginkgo/#pending-specs)
51 - [Focus](https://onsi.github.io/ginkgo/#focused-specs) individual specs, and groups of specs, either programmatically or on the command line
52 - Run your tests in [random order](https://onsi.github.io/ginkgo/#spec-permutation), and then reuse random seeds to replicate the same order.
53 - Break up your test suite into parallel processes for straightforward [test parallelization](https://onsi.github.io/ginkgo/#parallel-specs)
54
55- `ginkgo`: a command line interface with plenty of handy command line arguments for [running your tests](https://onsi.github.io/ginkgo/#running-tests) and [generating](https://onsi.github.io/ginkgo/#generators) test files. Here are a few choice examples:
56 - `ginkgo -nodes=N` runs your tests in `N` parallel processes and print out coherent output in realtime
57 - `ginkgo -cover` runs your tests using Go's code coverage tool
58 - `ginkgo convert` converts an XUnit-style `testing` package to a Ginkgo-style package
59 - `ginkgo -focus="REGEXP"` and `ginkgo -skip="REGEXP"` allow you to specify a subset of tests to run via regular expression
60 - `ginkgo -r` runs all tests suites under the current directory
61 - `ginkgo -v` prints out identifying information for each tests just before it runs
62
63 And much more: run `ginkgo help` for details!
64
65 The `ginkgo` CLI is convenient, but purely optional -- Ginkgo works just fine with `go test`
66
67- `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!
68
69- Built-in support for testing [asynchronicity](https://onsi.github.io/ginkgo/#asynchronous-tests)
70
71- Built-in support for [benchmarking](https://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.
72
73- [Completions for Sublime Text](https://github.com/onsi/ginkgo-sublime-completions): just use [Package Control](https://sublime.wbond.net/) to install `Ginkgo Completions`.
74
75- [Completions for VSCode](https://github.com/onsi/vscode-ginkgo): just use VSCode's extension installer to install `vscode-ginkgo`.
76
77- [Ginkgo tools for VSCode](https://marketplace.visualstudio.com/items?itemName=joselitofilho.ginkgotestexplorer): just use VSCode's extension installer to install `ginkgoTestExplorer`.
78
79- 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](https://onsi.github.io/ginkgo/#third-party-integrations) for details.
80
81- A modular architecture that lets you easily:
82 - Write [custom reporters](https://onsi.github.io/ginkgo/#writing-custom-reporters) (for example, Ginkgo comes with a [JUnit XML reporter](https://onsi.github.io/ginkgo/#generating-junit-xml-output) and a TeamCity reporter).
83 - [Adapt an existing matcher library (or write your own!)](https://onsi.github.io/ginkgo/#using-other-matcher-libraries) to work with Ginkgo
84
85## [Gomega](https://github.com/onsi/gomega): Ginkgo's Preferred Matcher Library
86
87Ginkgo is best paired with Gomega. Learn more about Gomega [here](https://onsi.github.io/gomega/)
88
89## [Agouti](https://github.com/sclevine/agouti): A Go Acceptance Testing Framework
90
91Agouti allows you run WebDriver integration tests. Learn more about Agouti [here](https://agouti.org)
92
93## Getting Started
94
95You'll need the Go command-line tools. Follow the [installation instructions](https://golang.org/doc/install) if you don't have it installed.
96
97### Global installation
98To install the Ginkgo command line interface:
99```bash
100go get -u github.com/onsi/ginkgo/ginkgo
101```
102Note that this will install it to `$GOBIN`, which will need to be in the `$PATH` (or equivalent). Run `go help install` for more information.
103
104### Go module ["tools package"](https://github.com/golang/go/issues/25922):
105Create (or update) a file called `tools/tools.go` with the following contents:
106```go
107// +build tools
108
109package tools
110
111import (
112 _ "github.com/onsi/ginkgo/ginkgo"
113)
114
115// This file imports packages that are used when running go generate, or used
116// during the development process but not otherwise depended on by built code.
117```
118The Ginkgo command can then be run via `go run github.com/onsi/ginkgo/ginkgo`.
119This approach allows the version of Ginkgo to be maintained under source control for reproducible results,
120and is well suited to automated test pipelines.
121
122### Bootstrapping
123```bash
124cd path/to/package/you/want/to/test
125
126ginkgo bootstrap # set up a new ginkgo suite
127ginkgo generate # will create a sample test file. edit this file and add your tests then...
128
129go test # to run your tests
130
131ginkgo # also runs your tests
132
133```
134
135## I'm new to Go: What are my testing options?
136
137Of 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.
138
139With that said, it's great to know what your options are :)
140
141### What Go gives you out of the box
142
143Testing is a first class citizen in Go, however Go's built-in testing primitives are somewhat limited: The [testing](https://golang.org/pkg/testing) package provides basic XUnit style tests and no assertion library.
144
145### Matcher libraries for Go's XUnit style tests
146
147A number of matcher libraries have been written to augment Go's built-in XUnit style tests. Here are two that have gained traction:
148
149- [testify](https://github.com/stretchr/testify)
150- [gocheck](https://labix.org/gocheck)
151
152You can also use Ginkgo's matcher library [Gomega](https://github.com/onsi/gomega) in [XUnit style tests](https://onsi.github.io/gomega/#using-gomega-with-golangs-xunitstyle-tests)
153
154### BDD style testing frameworks
155
156There are a handful of BDD-style testing frameworks written for Go. Here are a few:
157
158- [Ginkgo](https://github.com/onsi/ginkgo) ;)
159- [GoConvey](https://github.com/smartystreets/goconvey)
160- [Goblin](https://github.com/franela/goblin)
161- [Mao](https://github.com/azer/mao)
162- [Zen](https://github.com/pranavraja/zen)
163
164Finally, @shageman has [put together](https://github.com/shageman/gotestit) a comprehensive comparison of Go testing libraries.
165
166Go explore!
167
168## License
169
170Ginkgo is MIT-Licensed
171
172## Contributing
173
174See [CONTRIBUTING.md](CONTRIBUTING.md)
175
){kind=link}
){kind=link}
){kind=link}