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)