godog: github.com/DATA-DOG/godog Index | Files | Directories

package godog

import "github.com/DATA-DOG/godog"

Package godog is the official Cucumber BDD framework for Golang, it merges specification and test documentation into one cohesive whole.

Godog does not intervene with the standard "go test" command and it's behavior. You can leverage both frameworks to functionally test your application while maintaining all test related source code in *_test.go files.

Godog acts similar compared to go test command. It uses go compiler and linker tool in order to produce test executable. Godog contexts needs to be exported same as Test functions for go test.

For example, imagine you’re about to create the famous UNIX ls command. Before you begin, you describe how the feature should work, see the example below..


Feature: ls
  In order to see the directory structure
  As a UNIX user
  I need to be able to list the current directory's contents

	Given I am in a directory "test"
	And I have a file named "foo"
	And I have a file named "bar"
	When I run ls
	Then I should get output:

Now, wouldn’t it be cool if something could read this sentence and use it to actually run a test against the ls command? Hey, that’s exactly what this package does! As you’ll see, Godog is easy to learn, quick to use, and will put the fun back into tests.

Godog was inspired by Behat and Cucumber the above description is taken from it's documentation.


Package Files

ast.go builder_go110.go flags.go fmt.go fmt_cucumber.go fmt_events.go fmt_junit.go fmt_pretty.go fmt_progress.go gherkin.go godog.go options.go run.go stacktrace.go stepdef.go suite.go suite_context.go utils.go


const Version = "v0.7.14"

Version of package - based on Semantic Versioning 2.0.0 http://semver.org/


var ErrPending = fmt.Errorf("step implementation is pending")

ErrPending should be returned by step definition if step implementation is pending

var ErrUndefined = fmt.Errorf("step is undefined")

ErrUndefined is returned in case if step definition was not found

func AvailableFormatters Uses

func AvailableFormatters() map[string]string

AvailableFormatters gives a map of all formatters registered with their name as key and description as value

func BindFlags Uses

func BindFlags(prefix string, set *flag.FlagSet, opt *Options)

BindFlags binds godog flags to given flag set prefixed by given prefix, without overriding usage

func Build Uses

func Build(bin string) error

Build creates a test package like go test command at given target path. If there are no go files in tested directory, then it simply builds a godog executable to scan features.

If there are go test files, it first builds a test package with standard go test command.

Finally it generates godog suite executable which registers exported godog contexts from the test files of tested package.

Returns the path to generated executable

func FlagSet Uses

func FlagSet(opt *Options) *flag.FlagSet

FlagSet allows to manage flags by external suite runner builds flag.FlagSet with godog flags binded

func Format Uses

func Format(name, description string, f FormatterFunc)

Format registers a feature suite output formatter by given name, description and FormatterFunc constructor function, to initialize formatter with the output recorder.

func Run Uses

func Run(suite string, contextInitializer func(suite *Suite)) int

Run creates and runs the feature suite. Reads all configuration options from flags. uses contextInitializer to register contexts

the concurrency option allows runner to initialize a number of suites to be run separately. Only progress formatter is supported when concurrency level is higher than 1

contextInitializer must be able to register the step definitions and event handlers.

The exit codes may vary from:

0 - success
1 - failed
2 - command line usage error
128 - or higher, os signal related error exit codes

If there are flag related errors they will be directed to os.Stderr

func RunWithOptions Uses

func RunWithOptions(suite string, contextInitializer func(suite *Suite), opt Options) int

RunWithOptions is same as Run function, except it uses Options provided in order to run the test suite without parsing flags

This method is useful in case if you run godog in for example TestMain function together with go tests

The exit codes may vary from:

0 - success
1 - failed
2 - command line usage error
128 - or higher, os signal related error exit codes

If there are flag related errors they will be directed to os.Stderr

func SuiteContext Uses

func SuiteContext(s *Suite, additionalContextInitializers ...func(suite *Suite))

SuiteContext provides steps for godog suite execution and can be used for meta-testing of godog features/steps themselves.

Beware, steps or their definitions might change without backward compatibility guarantees. A typical user of the godog library should never need this, rather it is provided for those developing add-on libraries for godog.

For an example of how to use, see godog's own `features/` and `suite_test.go`.

type Formatter Uses

type Formatter interface {
    Feature(*gherkin.Feature, string, []byte)
    Defined(*gherkin.Step, *StepDef)
    Failed(*gherkin.Step, *StepDef, error)
    Passed(*gherkin.Step, *StepDef)
    Skipped(*gherkin.Step, *StepDef)
    Undefined(*gherkin.Step, *StepDef)
    Pending(*gherkin.Step, *StepDef)

Formatter is an interface for feature runner output summary presentation.

New formatters may be created to represent suite results in different ways. These new formatters needs to be registered with a godog.Format function call

type FormatterFunc Uses

type FormatterFunc func(string, io.Writer) Formatter

FormatterFunc builds a formatter with given suite name and io.Writer to record output

func FindFmt Uses

func FindFmt(name string) FormatterFunc

FindFmt searches available formatters registered and returns FormaterFunc matched by given format name or nil otherwise

type Options Uses

type Options struct {
    // Print step definitions found and exit
    ShowStepDefinitions bool

    // Randomize, if not `0`, will be used to run scenarios in a random order.
    // Randomizing scenario order is especially helpful for detecting
    // situations where you have state leaking between scenarios, which can
    // cause flickering or fragile tests.
    // The default value of `0` means "do not randomize".
    // The magic value of `-1` means "pick a random seed for me", and godog will
    // assign a seed on it's own during the `RunWithOptions` phase, similar to if
    // you specified `--random` on the command line.
    // Any other value will be used as the random seed for shuffling. Re-using the
    // same seed will allow you to reproduce the shuffle order of a previous run
    // to isolate an error condition.
    Randomize int64

    // Stops on the first failure
    StopOnFailure bool

    // Fail suite when there are pending or undefined steps
    Strict bool

    // Forces ansi color stripping
    NoColors bool

    // Various filters for scenarios parsed
    // from feature files
    Tags string

    // The formatter name
    Format string

    // Concurrency rate, not all formatters accepts this
    Concurrency int

    // All feature file paths
    Paths []string

    // Where it should print formatter output
    Output io.Writer

Options are suite run options flags are mapped to these options.

It can also be used together with godog.RunWithOptions to run test suite from go source directly

See the flags for more details

type StepDef Uses

type StepDef struct {
    Expr    *regexp.Regexp
    Handler interface{}
    // contains filtered or unexported fields

StepDef is a registered step definition contains a StepHandler and regexp which is used to match a step. Args which were matched by last executed step

This structure is passed to the formatter when step is matched and is either failed or successful

type Steps Uses

type Steps []string

Steps allows to nest steps instead of returning an error in step func it is possible to return combined steps:

func multistep(name string) godog.Steps {
  return godog.Steps{
    fmt.Sprintf(`an user named "%s"`, name),
    fmt.Sprintf(`user "%s" is authenticated`, name),

These steps will be matched and executed in sequential order. The first one which fails will result in main step failure.

type Suite Uses

type Suite struct {
    // contains filtered or unexported fields

Suite allows various contexts to register steps and event handlers.

When running a test suite, the instance of Suite is passed to all functions (contexts), which have it as a first and only argument.

Note that all event hooks does not catch panic errors in order to have a trace information. Only step executions are catching panic error since it may be a context specific error.

func (*Suite) AfterFeature Uses

func (s *Suite) AfterFeature(fn func(*gherkin.Feature))

AfterFeature registers a function or method to be run once after feature executed all scenarios.

func (*Suite) AfterScenario Uses

func (s *Suite) AfterScenario(fn func(interface{}, error))

AfterScenario registers an function or method to be run after every scenario or scenario outline

The interface argument may be *gherkin.Scenario or *gherkin.ScenarioOutline

func (*Suite) AfterStep Uses

func (s *Suite) AfterStep(fn func(*gherkin.Step, error))

AfterStep registers an function or method to be run after every scenario

It may be convenient to return a different kind of error in order to print more state details which may help in case of step failure

In some cases, for example when running a headless browser, to take a screenshot after failure.

func (*Suite) AfterSuite Uses

func (s *Suite) AfterSuite(fn func())

AfterSuite registers a function or method to be run once after suite runner

func (*Suite) BeforeFeature Uses

func (s *Suite) BeforeFeature(fn func(*gherkin.Feature))

BeforeFeature registers a function or method to be run once before every feature execution.

If godog is run with concurrency option, it will run every feature per goroutine. So user may choose whether to isolate state within feature context or scenario.

Best practice is not to have any state dependency on every scenario, but in some cases if VM for example needs to be started it may take very long for each scenario to restart it.

Use it wisely and avoid sharing state between scenarios.

func (*Suite) BeforeScenario Uses

func (s *Suite) BeforeScenario(fn func(interface{}))

BeforeScenario registers a function or method to be run before every scenario or scenario outline.

The interface argument may be *gherkin.Scenario or *gherkin.ScenarioOutline

It is a good practice to restore the default state before every scenario so it would be isolated from any kind of state.

func (*Suite) BeforeStep Uses

func (s *Suite) BeforeStep(fn func(*gherkin.Step))

BeforeStep registers a function or method to be run before every scenario

func (*Suite) BeforeSuite Uses

func (s *Suite) BeforeSuite(fn func())

BeforeSuite registers a function or method to be run once before suite runner.

Use it to prepare the test suite for a spin. Connect and prepare database for instance...

func (*Suite) Step Uses

func (s *Suite) Step(expr interface{}, stepFunc interface{})

Step allows to register a *StepDef in Godog feature suite, the definition will be applied to all steps matching the given Regexp expr.

It will panic if expr is not a valid regular expression or stepFunc is not a valid step handler.

Note that if there are two definitions which may match the same step, then only the first matched handler will be applied.

If none of the *StepDef is matched, then ErrUndefined error will be returned when running steps.


examples/apiExample - demonstrates REST API server implementation tests.
examples/godogsfile: $GOPATH/src/godogs/godogs.go

Package godog imports 30 packages (graph) and is imported by 42 packages. Updated 2019-04-15. Refresh now. Tools for package owners.