Categorygithub.com/jcsirot/ginkgo
modulepackage
1.6.0
Repository: https://github.com/jcsirot/ginkgo.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
18
Dependents
0
Files
328 SLOC

# README

Ginkgo: A Go BDD Testing Framework

Build Status

Jump to the docs to learn more. To start rolling your Ginkgo tests now keep reading!

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 and start writing your first tests

  • Structure your BDD-style tests expressively:

  • A comprehensive test runner that lets you:

    • Mark specs as pending
    • Focus individual specs, and groups of specs, either programmatically or on the command line
    • Run your tests in random order, and then reuse random seeds to replicate the same order.
    • Break up your test suite into parallel processes for straightforward test parallelization

  • ginkgo: a command line interface with plenty of handy command line arguments for running your tests and generating 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 Go'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 packages and their dependencies for changes, then reruns tests. Run tests immediately as you develop!

  • Built-in support for testing asynchronicity

  • Built-in support for benchmarking 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: just use Package Control to install Ginkgo Completions.

  • Completions for VSCode: just use VSCode's extension installer to install vscode-ginkgo.

  • Straightforward support for third-party testing libraries such as Gomock and Testify. Check out the docs for details.

  • A modular architecture that lets you easily:

Gomega: Ginkgo's Preferred Matcher Library

Ginkgo is best paired with Gomega. Learn more about Gomega here

Agouti: A Go Acceptance Testing Framework

Agouti allows you run WebDriver integration tests. Learn more about Agouti here

Set Me Up!

You'll need the Go command-line tools. Ginkgo is tested with Go 1.6+, but preferably you should get the latest. Follow the installation instructions if you don't have it installed.


go get -u github.com/onsi/ginkgo/ginkgo  # installs the ginkgo CLI
go get -u 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 and 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 Go gives you out of the box

Testing is a first class citizen in Go, however Go's built-in testing primitives are somewhat limited: The testing package provides basic XUnit style tests and no assertion library.

Matcher libraries for Go'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:

You can also use Ginkgo's matcher library Gomega in XUnit style tests

BDD style testing frameworks

There are a handful of BDD-style testing frameworks written for Go. Here are a few:

Finally, @shageman has put together a comprehensive comparison of Go testing libraries.

Go explore!

License

Ginkgo is MIT-Licensed

Contributing

See CONTRIBUTING.md

# Packages

Ginkgo accepts a number of configuration options.
No description provided by the author
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: ginkgo help Here are some of the more commonly used commands: To install: go install github.com/onsi/ginkgo/ginkgo To run tests: ginkgo To run tests in all subdirectories: ginkgo -r 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 ginkgo -p this will automatically detect the optimal number of nodes to use.
No description provided by the author
Ginkgo's Default Reporter A number of command line flags are available to tweak Ginkgo's default output.
No description provided by the author

# Functions

AfterEach blocks are run after It blocks.
AfterSuite blocks are *always* run after all the specs regardless of whether specs have passed or failed.Moreover, if Ginkgo receives an interrupt signal (^C) it will attempt to run the AfterSuite before exiting.
BeforeEach blocks are run before It blocks.
BeforeSuite blocks are run just once before any specs are run.
By allows you to better document large Its.
Context blocks allow you to organize your specs.
CurrentGinkgoTestDescripton returns information about the current running test.
Describe blocks allow you to organize your specs.
Fail notifies Ginkgo that the current spec has failed.
You can focus the tests within a describe block using FContext.
You can focus the tests within a describe block using FDescribe.
You can focus individual Its using FIt.
You can focus individual Measures using FMeasure.
You can focus individual Specifys using FSpecify.
You can focus the tests within a describe block using FWhen.
GinkgoParallelNode returns the parallel node number for the current ginkgo processThe node number is 1-indexed.
GinkgoRandomSeed returns the seed used to randomize spec execution order.
GinkgoRecover should be deferred at the top of any spawned goroutine that (may) call `Fail`Since Gomega assertions call fail, you should throw a `defer GinkgoRecover()` at the top of any goroutine thatcalls out to Gomega Here's why: Ginkgo's `Fail` method records the failure and then panics to preventfurther assertions from running.
Some matcher libraries or legacy codebases require a *testing.TGinkgoT implements an interface analogous to *testing.T and can be used ifthe library in question accepts *testing.T through an interface For example, with testify: assert.Equal(GinkgoT(), 123, 123, "they should be equal") Or with gomock: gomock.NewController(GinkgoT()) GinkgoT() takes an optional offset argument that can be used to get the correct line number associated with the failure.
It blocks contain your test code and assertions.
JustBeforeEach blocks are run before It blocks but *after* all BeforeEach blocks.
Measure blocks run the passed in body function repeatedly (determined by the samples argument)and accumulate metrics provided to the Benchmarker by the body function.
You can mark the tests within a describe block as pending using PContext.
You can mark the tests within a describe block as pending using PDescribe.
You can mark Its as pending using PIt.
You can mark Maeasurements as pending using PMeasure.
You can mark Specifys as pending using PSpecify.
You can mark the tests within a describe block as pending using PWhen.
RunSpecs is the entry point for the Ginkgo test runner.You must call this within a Golang testing TestX(t *testing.T) function.
To run your tests with your custom reporter(s) (and *not* Ginkgo's default reporter), replaceRunSpecs() with this method.
To run your tests with Ginkgo's default reporter and your custom reporter(s), replaceRunSpecs() with this method.
Skip notifies Ginkgo that the current spec was skipped.
Specify blocks are aliases for It blocks and allow for more natural wording in situationswhich "It" does not fit into a natural sentence flow.
SynchronizedAfterSuite blocks complement the SynchronizedBeforeSuite blocks in solving the problem of setting upexternal singleton resources shared across nodes when running tests in parallel.
SynchronizedBeforeSuite blocks are primarily meant to solve the problem of setting up singleton external resources shared acrossnodes when running tests in parallel.
When blocks allow you to organize your specs.
You can mark the tests within a describe block as pending using XContext.
You can mark the tests within a describe block as pending using XDescribe.
You can mark Its as pending using XIt.
You can mark Maeasurements as pending using XMeasure.
You can mark Specifys as pending using XSpecify.
You can mark the tests within a describe block as pending using XWhen.

# Constants

No description provided by the author
No description provided by the author

# Variables

GinkgoWriter implements an io.WriterWhen running in verbose mode any writes to GinkgoWriter will be immediately printedto stdout.

# Structs

GinkgoTestDescription represents the information about the current running test returned by CurrentGinkgoTestDescription FullTestText: a concatenation of ComponentTexts and the TestText ComponentTexts: a list of all texts for the Describes & Contexts leading up to the current test TestText: the text in the actual It or Measure node IsMeasurement: true if the current test is a measurement FileName: the name of the file containing the current test LineNumber: the line number for the current test Failed: if the current test has failed, this will be true (useful in an AfterEach).

# Interfaces

Measurement tests receive a Benchmarker.
The interface by which Ginkgo receives *testing.T.
The interface returned by GinkgoT().

# Type aliases

Custom Ginkgo test reporters must implement the Reporter interface.