godog

README

Godog

The API is likely to change a few times before we reach 1.0.0

Package godog is the official Cucumber BDD framework for Golang, it merges specification and test documentation into one cohesive whole. The author is a core member of cucumber team.

What is behavior-driven development, you ask? It’s the idea that you start by writing human-readable sentences that describe a feature of your application and how it should work, and only then implement this behavior in software.

The project is inspired by behat and cucumber and is based on cucumber gherkin3 parser.

Godog does not intervene with the standard go test command and its 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.

Godog ships gherkin parser dependency as a subpackage. This will ensure that it is always compatible with the installed version of godog. So in general there are no vendor dependencies needed for installation.

The following about section was taken from cucumber homepage.

About

A single source of truth

Cucumber merges specification and test documentation into one cohesive whole.

Living documentation

Because they're automatically tested by Cucumber, your specifications are always bang up-to-date.

Focus on the customer

Business and IT don't always understand each other. Cucumber's executable specifications encourage closer collaboration, helping teams keep the business goal in mind at all times.

Less rework

When automated testing is this much fun, teams can easily protect themselves from costly regressions.

Install

go get github.com/DATA-DOG/godog/cmd/godog

Example

The following example can be found here.

Step 1

Given we create a new go package $GOPATH/src/godogs. From now on, this is our work directory cd $GOPATH/src/godogs.

Imagine we have a godog cart to serve godogs for lunch. First of all, we describe our feature in plain text - vim $GOPATH/src/godogs/features/godogs.feature:

# file: $GOPATH/src/godogs/features/godogs.feature
Feature: eat godogs
  In order to be happy
  As a hungry gopher
  I need to be able to eat godogs

  Scenario: Eat 5 out of 12
    Given there are 12 godogs
    When I eat 5
    Then there should be 7 remaining

As a developer, your work is done as soon as you’ve made the program behave as described in the Scenario.

NOTE: same as go test godog respects package level isolation. All your step definitions should be in your tested package root directory. In this case - $GOPATH/src/godogs

Step 2

If godog is installed in your GOPATH. We can run godog inside the $GOPATH/src/godogs directory. You should see that the steps are undefined:

If we wish to vendor godog dependency, we can do it as usual, using tools you prefer:

git clone https://github.com/DATA-DOG/godog.git $GOPATH/src/godogs/vendor/github.com/DATA-DOG/godog

It gives you undefined step snippets to implement in your test context. You may copy these snippets into your godogs_test.go file.

Our directory structure should now look like:

If you copy the snippets into our test file and run godog again. We should see the step definition is now pending:

You may change ErrPending to nil and the scenario will pass successfully.

Since we need a working implementation, we may start by implementing only what is necessary.

Step 3

We only need a number of godogs for now. Lets keep it simple.

/* file: $GOPATH/src/godogs/godogs.go */
package main

// Godogs available to eat
var Godogs int

func main() { /* usual main func */ }

Step 4

Now lets implement our step definitions, which we can copy from generated console output snippets in order to test our feature requirements:

/* file: $GOPATH/src/godogs/godogs_test.go */
package main

import (
	"fmt"

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

func thereAreGodogs(available int) error {
	Godogs = available
	return nil
}

func iEat(num int) error {
	if Godogs < num {
		return fmt.Errorf("you cannot eat %d godogs, there are %d available", num, Godogs)
	}
	Godogs -= num
	return nil
}

func thereShouldBeRemaining(remaining int) error {
	if Godogs != remaining {
		return fmt.Errorf("expected %d godogs to be remaining, but there is %d", remaining, Godogs)
	}
	return nil
}

func FeatureContext(s *godog.Suite) {
	s.Step(`^there are (\d+) godogs$`, thereAreGodogs)
	s.Step(`^I eat (\d+)$`, iEat)
	s.Step(`^there should be (\d+) remaining$`, thereShouldBeRemaining)

	s.BeforeScenario(func(interface{}) {
		Godogs = 0 // clean the state before every scenario
	})
}

Now when you run the godog again, you should see:

Note: we have hooked to BeforeScenario event in order to reset state. You may hook into more events, like AfterStep to test against an error and print more details about the error or state before failure. Or BeforeSuite to prepare a database.

Running Godog with go test

There was a question asked whether it is possible to run godog from go test command. And the answer is yes. You can run it using go TestMain func available since go 1.4. In this case it is not necessary to have godog command installed. See the following example:

/* file: $GOPATH/src/godogs/godogs_test.go */
package main

import (
	"os"
	"testing"

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

func TestMain(m *testing.M) {
	status := godog.RunWithOptions("godogs", func(s *godog.Suite) {
		FeatureContext(s)
	}, godog.Options{
		Format: "progress",
		Paths:  []string{"features"},
	})

	if st := m.Run(); st > status {
		status = st
	}
	os.Exit(status)
}

References and Tutorials

• how to use godog by semaphoreci

Documentation

See godoc for general API details. See .travis.yml for supported go versions. See godog -h for general command options.

See implementation examples:

• rest API server
• rest API with Database
• godogs

FAQ

Q: Where can I configure common options globally? A: You can't. Alias your common or project based commands: alias godog-wip="godog --format=progress --tags=@wip"

Contributions

Feel free to open a pull request. Note, if you wish to contribute an extension to public (exported methods or types) - please open an issue before to discuss whether these changes can be accepted. All backward incompatible changes are and will be treated cautiously.

License

All package dependencies are MIT or BSD licensed.

Godog is licensed under the three clause BSD license

Documentation

Overview

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..

Example:

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

  Scenario:
	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:
	  """
	  bar
	  foo
	  """

As a developer, your work is done as soon as you’ve made the ls command behave as described in the Scenario.

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.

Index

• Constants
• Variables
• func AvailableFormatters() map[string]string
• func Build(bin string) error
• func FlagSet(opt *Options) *flag.FlagSet
• func Format(name, description string, f FormatterFunc)
• func Run(suite string, contextInitializer func(suite *Suite)) int
• func RunWithOptions(suite string, contextInitializer func(suite *Suite), opt Options) int
• type Formatter
• type FormatterFunc
• type Options
• type StepDef
• type Suite
  • func (s *Suite) AfterScenario(f func(interface{}, error))
  • func (s *Suite) AfterStep(f func(*gherkin.Step, error))
  • func (s *Suite) AfterSuite(f func())
  • func (s *Suite) BeforeScenario(f func(interface{}))
  • func (s *Suite) BeforeStep(f func(*gherkin.Step))
  • func (s *Suite) BeforeSuite(f func())
  • func (s *Suite) Step(expr interface{}, stepFunc interface{})

Constants

const Version = "v0.6.2"

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

Variables

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

Functions

func AvailableFormatters

func AvailableFormatters() map[string]string

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

func Build

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

func FlagSet(opt *Options) *flag.FlagSet

FlagSet allows to manage flags by external suite runner

func Format

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

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.

func RunWithOptions

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

Types

type Formatter

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

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

type FormatterFunc func(string, io.Writer) Formatter

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

type Options

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

	// Stops on the first failure
	StopOnFailure 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

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 Suite

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) AfterScenario

func (s *Suite) AfterScenario(f 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

func (s *Suite) AfterStep(f 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

func (s *Suite) AfterSuite(f func())

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

func (*Suite) BeforeScenario

func (s *Suite) BeforeScenario(f 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

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

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

func (*Suite) BeforeSuite

func (s *Suite) BeforeSuite(f 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

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.