github.com/onsi/ginkgo@v1.16.6-0.20211118180735-4e1925ba4c95/README.md (about) 1 ![Ginkgo](https://onsi.github.io/ginkgo/images/ginkgo.png) 2 3 [![test](https://github.com/onsi/ginkgo/workflows/test/badge.svg?branch=master)](https://github.com/onsi/ginkgo/actions?query=workflow%3Atest+branch%3Amaster) 4 5 Ginkgo is a mature, well-established, testing framework for Go designed to help you write expressive specs. Ginkgo builds on top of Go's `testing` foundation and is complemented by the [Gomega](https://github.com/onsi/gomega) matcher library. Together, Ginkgo and Gomega let you express the intent behind your specs clearly: 6 7 ```go 8 import ( 9 . "github.com/onsi/ginkgo" 10 . "github.com/onsi/gomega" 11 ... 12 ) 13 14 Describe("Checking books out of the library", func() { 15 var library *libraries.Library 16 var book *books.Book 17 var valjean *users.User 18 BeforeEach(func() { 19 library = libraries.NewClient() 20 book = &books.Book{ 21 Title: "Les Miserables", 22 Author: "Victor Hugo", 23 } 24 valjean = users.NewUser("Jean Valjean") 25 }) 26 27 When("the library has the book in question", func() { 28 BeforeEach(func() { 29 Expect(library.Store(book)).To(Succeed()) 30 }) 31 32 Context("and the book is available", func() { 33 It("lends it to the reader", func() { 34 Expect(valjean.Checkout(library, "Les Miserables")).To(Succeed()) 35 Expect(valjean.Books()).To(ContainElement(book)) 36 Expect(library.UserWithBook(book)).To(Equal(valjean)) 37 }) 38 }) 39 40 Context("but the book has already been checked out", func() { 41 var javert *users.User 42 BeforeEach(func() { 43 javert = users.NewUser("Javert") 44 Expect(javert.Checkout(library, "Les Miserables")).To(Succeed()) 45 }) 46 47 It("tells the user", func() { 48 err := valjean.Checkout(library, "Les Miserables") 49 Expect(error).To(MatchError("Les Miserables is currently checked out")) 50 }) 51 52 It("lets the user place a hold and get notified later", func() { 53 Expect(valjean.Hold(library, "Les Miserables")).To(Succeed()) 54 Expect(valjean.Holds()).To(ContainElement(book)) 55 56 By("when Javert returns the book") 57 Expect(javert.Return(library, book)).To(Succeed()) 58 59 By("it eventually informs Valjean") 60 notification := "Les Miserables is ready for pick up" 61 Eventually(valjean.Notifications).Should(ContainElement(notification)) 62 63 Expect(valjean.Checkout(library, "Les Miserables")).To(Succeed()) 64 Expect(valjean.Books()).To(ContainElement(book)) 65 Expect(valjean.Holds()).To(BeEmpty()) 66 }) 67 }) 68 }) 69 70 When("the library does not have the book in question", func() { 71 It("tells the reader the book is unavailable", func() { 72 err := valjean.Checkout(library, "Les Miserables") 73 Expect(error).To(MatchError("Les Miserables is not in the library catalog")) 74 }) 75 }) 76 }) 77 ``` 78 79 Jump to the [docs](https://onsi.github.io/ginkgo/) to learn more! It's easy to [bootstrap](https://onsi.github.io/ginkgo/#bootstrapping-a-suite) and start writing your [first specs](https://onsi.github.io/ginkgo/#adding-specs-to-a-suite). 80 81 If 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). 82 83 ## Capabilities 84 85 Whether writing basic unit specs, complex integration specs, or even performance specs - Ginkgo gives you an expressive Domain-Specific Language (DSL) that will be familiar to users coming from frameworks such as [Quick](https://github.com/Quick/Quick), [RSpec](https://rspec.info), [Jasmine](https://jasmine.github.io), [Busted](https://olivinelabs.com/busted/). This style of testing is sometimes referred to as "Behavior-Driven Development" (BDD) though Ginkgo's utility extends beyond acceptance-level testing. 86 87 With Ginkgo's DSL you can use nestable [`Describe`, `Context` and `When` container nodes](https://onsi.github.io/ginkgo/#organizing-specs-with-container-nodes) to help you organize your specs. [`BeforeEach` and `AfterEach` setup nodes](https://onsi.github.io/ginkgo/#extracting-common-setup-beforeeach) for setup and cleanup. [`It` and `Specify` subject nodes](https://onsi.github.io/ginkgo/#spec-subjects-it) that hold your assertions. [`BeforeSuite` and `AfterSuite` nodes](https://onsi.github.io/ginkgo/#suite-setup-and-cleanup-beforesuite-and-aftersuite) to prep for and cleanup after a suite... and [much more!](https://onsi.github.io/ginkgo/#writing-specs) 88 89 At runtime, Ginkgo can run your specs in reproducibly [random order](https://onsi.github.io/ginkgo/#spec-randomization) and has sophisticated support for [spec parallelization](https://onsi.github.io/ginkgo/#spec-parallelization). In fact, running specs in parallel is as easy as 90 91 ```bash 92 ginkgo -p 93 ``` 94 95 By following [established patterns for writing parallel specs](https://onsi.github.io/ginkgo/#patterns-for-parallel-integration-specs) you can build even large, complex integration suites that parallelize cleanly and run performantly. 96 97 As your suites grow Ginkgo helps you keep your specs organized with [labels](https://onsi.github.io/ginkgo/#spec-labels) and lets you easily run [subsets of specs](https://onsi.github.io/ginkgo/#filtering-specs), either [programatically](https://onsi.github.io/ginkgo/#focused-specs) or on the [command line](https://onsi.github.io/ginkgo/#combining-filters). And Ginkgo's reporting infrastructure will generate machine-readable output in a [variety of formats](https://onsi.github.io/ginkgo/#generating-machine-readable-reports) _and_ allow you to build your own [custom reporting infrastructure](https://onsi.github.io/ginkgo/#generating-reports-programmatically). 98 99 Ginkgo ships with `ginkgo`, a [command line tool](https://onsi.github.io/ginkgo/#ginkgo-cli-overview) with powerful support for generating, running, filtering, and profiling Ginkgo suites. You can even have Ginkgo automatically run your specs when it detects a change with `ginkgo watch`, enabling rapid feedback loops during test-driven development. 100 101 And that's just Ginkgo! [Gomega](https://onsi.github.io/gomega/) brings a rich, mature, family of [assertions and matchers](https://onsi.github.io/gomega/#provided-matchers) to your suites. With Gomega you can easily mix [synchronous and asynchronous assertions](https://onsi.github.io/ginkgo/#patterns-for-asynchronous-testing) in your specs. You can even build your own set of expressive domain-specific matchers quickly and easily by composing Gomega's [existing building blocks](https://onsi.github.io/ginkgo/#building-custom-matchers). 102 103 Happy Testing! 104 105 ## License 106 107 Ginkgo is MIT-Licensed 108 109 ## Contributing 110 111 See [CONTRIBUTING.md](CONTRIBUTING.md)