Gucumber is Cucumber for Go

By Loren Segal on March 30th, 2015 at 2:08 PM

This last week I finished initial work on a Cucumber implementation in Go called Gucumber and released it on GitHub. Gucumber is a BDD-style testing framework that allows you to execute Gherkin .feature files in the Go programming language.

Gucumber supports most of the basic Gherkin syntax, including features, scenarios, scenario outlines, docstring and tabular data. In addition, the CLI and step definitions also support tag filters and before-after hooks.


Installing with Go should be as simple as:

$ go get -u


If you’ve used Cucumber before, the library and CLI are fairly straightforward and similar to other language implementations. You can see an example in the features directory of the Gucumber package itself.

Given a .feature file:

# features/basic/basic.feature
Feature: Basic support
  This package should support the use of scenarios.

  Scenario: Basic usage
    Given I have an initial value of 3
    And I add 3 to the value
    Then I should have 6

And a step definition file:

# features/basic/step_definitions.go
package basic

import (
    . ""

func init() {
    var initVal int

    Given(`^I have an initial value of (d+)$`, func(val int) {
        initVal = val

    And(`^I add (d+) to the value$`, func(val int) {
        initVal += val

    Then(`^I should have (d+)$`, func(val int) {
        assert.Equal(T, val, initVal)

You can run gucumber to run these tests, which executes from the features directory by default, but can any path can be passed to the CLI:

$ gucumber
Feature: Basic support
  Scenario: Basic usage                 # features/basic/basic.feature:3
    Given I have an initial value of 3  # features/basic/basic.feature:4
    And I add 3 to the value            # features/basic/basic.feature:5
    Then I should have 6                # features/basic/basic.feature:8

Finished (3 passed, 0 failed, 0 skipped).

Writing Step Definitions

Gucumber by default pulls in all .go files in the features directory being executed. You might have noticed a few things about these files:

  1. The Given, When and other step definition functions are used without the gucumber package prefix. In my examples, I choose to import gucumber into the global namespace to simplify definitions. While this is not required (you can just as easily import in a more traditional way), I would recommend it for simplicity in these files.
  2. The global (also can be prefixed) T value, which seems to represent a test context and is passed into test assertions. I use testify/assert as a personal choice, but Gucumber should support most testing libraries, including Go’s own testing.T style. If the assertion library you use is not working, please open an issue.

Future Work

Gucumber is not yet complete, but it is also in a fairly usable state. Error reporting of test failures and other runner summary information can be improved, and patches would be accepted to bring this implementation up to speed with others. Check it out and let me know how it works for you.

Get It Now!

You can get Gucumber and/or more information on GitHub!

Questions? Comments? Follow me on Twitter (@lsegal) or email me.