Skip to content
Cucumber for golang
Go Gherkin Makefile
Branch: master
Clone or download

Latest commit

lonnblad Merge pull request #298 from cucumber/parallel-build-tests
Made the builder tests run in parallel
Latest commit 1deee10 May 27, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Moved the fmt tests to a godog_test pkg and restructured the fmt outp… May 22, 2020
.github/ISSUE_TEMPLATE Update issue templates Mar 14, 2020
_examples Readded some legacy doc for FeatureContext May 23, 2020
cmd/godog Change data-dog/godog references to cucumber/godog Feb 6, 2020
colors Updated linting checks in circleci config and fixed linting issues May 3, 2020
features Added a missed test file and updated the CHANGELOG Apr 30, 2020
formatter-tests Moved the fmt tests to a godog_test pkg and restructured the fmt outp… May 22, 2020
release-notes Fixed final release doc for v0.9.0 Mar 22, 2020
screenshots update godog usage example with more details Jun 17, 2016
.gitignore <fix>(PRETIFIER): Fix s method to not have errors on negative entry Mar 9, 2020
CHANGELOG.md Update CHANGELOG.md May 23, 2020
CHANGELOG_OLD.md Switch to new CHANGELOG and bump version to 0.8.0 Feb 6, 2020
CONTRIBUTING.md Merge branch 'master' into release/v0.9.0 Mar 16, 2020
LICENSE Fix typo Feb 4, 2020
Makefile Rename examples to _examples Feb 10, 2020
README.md Update README.md May 25, 2020
ast.go Added the new TestSuiteInitializer and ScenarioInitializer May 18, 2020
ast_test.go Added the new TestSuiteInitializer and ScenarioInitializer May 18, 2020
builder.go Added the new TestSuiteInitializer and ScenarioInitializer May 18, 2020
builder_go112_test.go Made the builder tests run in parallel May 24, 2020
builder_go113_test.go Made the builder tests run in parallel May 24, 2020
builder_go_module_test.go Made the builder tests run in parallel May 24, 2020
builder_test.go Made the builder tests run in parallel May 24, 2020
flags.go Change data-dog/godog references to cucumber/godog Feb 6, 2020
flags_test.go Change data-dog/godog references to cucumber/godog Feb 6, 2020
fmt.go Moved the fmt tests to a godog_test pkg and restructured the fmt outp… May 22, 2020
fmt_color_tag_test.go Moved the fmt tests to a godog_test pkg and restructured the fmt outp… May 22, 2020
fmt_cucumber.go Added concurrency support to the cucumber formatter Mar 26, 2020
fmt_events.go Added concurrency support to the events formatter Mar 26, 2020
fmt_junit.go Revert "Revert "Migrated to github.com/cucumber/gherkin-go - v9.2.0"" Mar 9, 2020
fmt_output_test.go Moved the fmt tests to a godog_test pkg and restructured the fmt outp… May 22, 2020
fmt_pretty.go Added concurrency support to the pretty formatter Mar 26, 2020
fmt_progress.go Upgraded gherkin-go and messages-go to latest Mar 12, 2020
fmt_progress_test.go Moved the fmt tests to a godog_test pkg and restructured the fmt outp… May 22, 2020
fmt_test.go Moved the fmt tests to a godog_test pkg and restructured the fmt outp… May 22, 2020
go.mod Downgraded go version in go.mod Mar 12, 2020
go.sum Upgraded gherkin-go and messages-go to latest Mar 12, 2020
godog.go Fixed final release doc for v0.9.0 Mar 22, 2020
logo.png Replaced loco.png with better quality image and added a vector logo Dec 19, 2018
logo.svg Replaced loco.png with better quality image and added a vector logo Dec 19, 2018
options.go adds --strict flag to fail suite when there are pending or undefined … May 4, 2017
run.go Added the new TestSuiteInitializer and ScenarioInitializer May 18, 2020
run_test.go Updated so that we run all tests concurrent now Mar 26, 2020
stacktrace.go fixes stack trace test Apr 28, 2017
stacktrace_test.go Made progress formatter verification a bit more accurate Mar 24, 2020
stepdef.go Upgraded gherkin-go and messages-go to latest Mar 12, 2020
stepdef_test.go Upgraded gherkin-go and messages-go to latest Mar 12, 2020
suite.go Added the new TestSuiteInitializer and ScenarioInitializer May 18, 2020
suite_context.go Added concurrency support to the pretty formatter Mar 26, 2020
suite_test.go Remove TestMain call Mar 5, 2020
tag_filter_test.go Upgraded gherkin-go and messages-go to latest Mar 12, 2020
test_context.go Added the new TestSuiteInitializer and ScenarioInitializer May 18, 2020
test_context_test.go Added the new TestSuiteInitializer and ScenarioInitializer May 18, 2020
undefined_snippets_gen.go Added sorting for undefined snippets on method name Mar 24, 2020
utils.go Clean change on pretty. Make test on new TC meaningfull again. Mar 9, 2020
utils_test.go tests junit formatter Apr 28, 2017

README.md

CircleCI GoDoc codecov

Godog

Godog logo

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

Please read all the README, you may find it very useful. And do not forget to peek into the CHANGELOG from time to time.

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

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 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, by using go compiler and linker tool in order to produce test executable. Godog contexts need to be exported the same way as Test functions for go tests. Note, that if you use godog command tool, it will use go executable to determine compiler and linker.

Godog depends on gherkin-go and messages-go.

The following about section was taken from cucumber homepage.

Notice:

If your project depend on the master version of godog instead of a specific release, please read this.

Due to dependency changes in a coming merge to master, including breaking changes, you should update how you install or depend on godog so that you have a version specified.

Install

go get github.com/cucumber/godog/cmd/godog@v0.9.0

Adding @v0.9.0 will install v0.9.0 specifically instead of master.

Running within the $GOPATH, you would also need to set GO111MODULE=on, like this:

GO111MODULE=on go get github.com/cucumber/godog/cmd/godog@v0.9.0

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.

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

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:

Undefined step snippets

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

git clone https://github.com/cucumber/godog.git $GOPATH/src/godogs/vendor/github.com/cucumber/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:

Directory layout

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

Pending step definition

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.

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:

package main

import (
	"fmt"
	
	messages "github.com/cucumber/messages-go/v10" // needed for godog v0.9.0 (latest) and earlier

	"github.com/cucumber/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
}

// godog v0.9.0 (latest) and earlier
func FeatureContext(s *godog.Suite) {
	s.BeforeSuite(func() { Godogs = 0 })

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

	s.Step(`^there are (\d+) godogs$`, thereAreGodogs)
	s.Step(`^I eat (\d+)$`, iEat)
	s.Step(`^there should be (\d+) remaining$`, thereShouldBeRemaining)
}

// godog v0.10.0 (coming release)
func InitializeTestSuite(ctx *godog.TestSuiteContext) {
	ctx.BeforeSuite(func() { Godogs = 0 })
}

func InitializeScenario(ctx *godog.ScenarioContext) {
	ctx.BeforeScenario(func(*godog.Scenario) {
		Godogs = 0 // clean the state before every scenario
	})

	ctx.Step(`^there are (\d+) godogs$`, thereAreGodogs)
	ctx.Step(`^I eat (\d+)$`, iEat)
	ctx.Step(`^there should be (\d+) remaining$`, thereShouldBeRemaining)
}

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

Passed suite

We have hooked to BeforeScenario event in order to reset application state before each scenario. You may hook into more events, like AfterStep to print all state in case of an error. Or BeforeSuite to prepare a database.

By now, you should have figured out, how to use godog. Another advice is to make steps orthogonal, small and simple to read for a user. Whether the user is a dumb website user or an API developer, who may understand a little more technical context - it should target that user.

When steps are orthogonal and small, you can combine them just like you do with Unix tools. Look how to simplify or remove ones, which can be composed.

References and Tutorials

Documentation

See godoc for general API details. See Circle Config for supported go versions. See godog -h for general command options.

See implementation examples:

FAQ

Running Godog with go test

You may integrate running godog in your go test command. 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 examples.

The following example binds godog flags with specified prefix godog in order to prevent flag collisions.

var opts = godog.Options{
	Output: colors.Colored(os.Stdout),
	Format: "progress", // can define default values
}

func init() {
	godog.BindFlags("godog.", flag.CommandLine, &opts)
}

func TestMain(m *testing.M) {
	flag.Parse()
	opts.Paths = flag.Args()

	// godog v0.9.0 (latest) and earlier
	status := godog.RunWithOptions("godogs", func(s *godog.Suite) {
		FeatureContext(s)
	}, opts)

	// godog v0.10.0 (coming release)
	status := godog.TestSuite{
		Name: "godogs",
		TestSuiteInitializer: InitializeTestSuite,
		ScenarioInitializer:  InitializeScenario,
		Options: &opts,
	}.Run()

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

Then you may run tests with by specifying flags in order to filter features.

go test -v --godog.random --godog.tags=wip
go test -v --godog.format=pretty --godog.random -race -coverprofile=coverage.txt -covermode=atomic

The following example does not bind godog flags, instead manually configuring needed options.

func TestMain(m *testing.M) {
	opts := godog.Options{
		Format:    "progress",
		Paths:     []string{"features"},
		Randomize: time.Now().UTC().UnixNano(), // randomize scenario execution order
	}

	// godog v0.9.0 (latest) and earlier
	status := godog.RunWithOptions("godogs", func(s *godog.Suite) {
		FeatureContext(s)
	}, opts)

	// godog v0.10.0 (coming release)
	status := godog.TestSuite{
		Name: "godogs",
		TestSuiteInitializer: InitializeTestSuite,
		ScenarioInitializer:  InitializeScenario,
		Options: &opts,
	}.Run()

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

You can even go one step further and reuse go test flags, like verbose mode in order to switch godog format. See the following example:

func TestMain(m *testing.M) {
	format := "progress"
	for _, arg := range os.Args[1:] {
		if arg == "-test.v=true" { // go test transforms -v option
			format = "pretty"
			break
		}
	}

	opts := godog.Options{
		Format: format,
		Paths:     []string{"features"},
	}

	// godog v0.9.0 (latest) and earlier
	status := godog.RunWithOptions("godogs", func(s *godog.Suite) {
		FeatureContext(s)
	}, opts)

	// godog v0.10.0 (coming release)
	status := godog.TestSuite{
		Name: "godogs",
		TestSuiteInitializer: InitializeTestSuite,
		ScenarioInitializer:  InitializeScenario,
		Options: &opts,
	}.Run()

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

Now when running go test -v it will use pretty format.

Tags

If you want to filter scenarios by tags, you can use the -t=<expression> or --tags=<expression> where <expression> is one of the following:

  • @wip - run all scenarios with wip tag
  • ~@wip - exclude all scenarios with wip tag
  • @wip && ~@new - run wip scenarios, but exclude new
  • @wip,@undone - run wip or undone scenarios

Using assertion packages like testify with Godog

A more extensive example can be found here.

func thereShouldBeRemaining(remaining int) error {
	return assertExpectedAndActual(
		assert.Equal, Godogs, remaining,
		"Expected %d godogs to be remaining, but there is %d", remaining, Godogs,
	)
}

// assertExpectedAndActual is a helper function to allow the step function to call
// assertion functions where you want to compare an expected and an actual value.
func assertExpectedAndActual(a expectedAndActualAssertion, expected, actual interface{}, msgAndArgs ...interface{}) error {
	var t asserter
	a(&t, expected, actual, msgAndArgs...)
	return t.err
}

type expectedAndActualAssertion func(t assert.TestingT, expected, actual interface{}, msgAndArgs ...interface{}) bool

// asserter is used to be able to retrieve the error reported by the called assertion
type asserter struct {
	err error
}

// Errorf is used by the called assertion to report an error
func (a *asserter) Errorf(format string, args ...interface{}) {
	a.err = fmt.Errorf(format, args...)
}

Configure common options for godog CLI

There are no global options or configuration files. Alias your common or project based commands: alias godog-wip="godog --format=progress --tags=@wip"

Testing browser interactions

godog does not come with builtin packages to connect to the browser. You may want to look at selenium and probably phantomjs. See also the following components:

  1. browsersteps - provides basic context steps to start selenium and navigate browser content.
  2. You may wish to have goquery in order to work with HTML responses like with JQuery.

Concurrency

In order to support concurrency well, you should reset the state and isolate each scenario. They should not share any state. It is suggested to run the suite concurrently in order to make sure there is no state corruption or race conditions in the application.

It is also useful to randomize the order of scenario execution, which you can now do with --random command option.

NOTE: if suite runs with concurrency option, it concurrently runs every feature, not scenario per different features. This gives a flexibility to isolate state per feature. For example using BeforeFeature hook, it is possible to spin up costly service and shut it down only in AfterFeature hook and share the service between all scenarios in that feature. It is not advisable though, because you are risking having a state dependency.

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.

Reach out to the community on our Cucumber Slack Community. Join here.

Popular Cucumber Slack channels for Godog:

License

  • Godog is licensed under the MIT
  • Gherkin is licensed under the MIT and developed as a part of the cucumber project
You can’t perform that action at this time.