gorkin

gorkin is an experimental implementation of cucumber for Go.

gorkin is designed to enable developers to write tests against feature files utilizing the standard Go testing framework. I wanted to make it easy for developers to be handed user stories and use their existing tools to write tests in ways they were familiar with. To that end, I’ve tried very hard to minimize the framework needed to hook into gorkin.

Cucumber user stories look like this:

Feature: My First Feature
  In order to understand how to use gorkin
  A new gorkin user will need a feature example with a corresponding test.

  Scenario: A User Visits the gorkin Site
    Given a new user visits the gorkin site
    Then they should see 3 examples.

And a corresponding gorkin test might look something like this:

package example

import (
    . "testing"
    "fmt"

    . "github.com/kat-co/gorkin/gorkin"
)

// I is a structure designed to isolate testing state. For each
// scenario, a new one of these will be instantiated and passed to
// test steps when requested.
type I struct {}

// Steps can be registered anywhere. The only stipulation is that they
// all be registered before the call to RunFeatureTests is made. Since
// step registration may need to be spread across several files, the
// init function is a good choice.
//
// The step's function signature can also be whatever you'd like it to
// be. In most cases, gorkin will do the right thing.
func init() {
    Step(`a new user visits the gorkin site`, func() {
        fmt.Println("visit the gorkin site here...")
    })

    // Here we see an example of how to match an element of a
    // scenario's step so that we can utilize it in the step's
    // function definition. gorkin will automatically perform the type
    // conversion.
    Step(`they should see ([0-9]+) example(?:s)?`, func(t *T, numExamples int) {
        t.Logf("user should see %d", numExamples)
    })
}

func Test(t *T) {
    // RunFeatureTests registers Go's testing runner and your
    // isolation type with Gorkin and then runs the defined steps
    // against any feature files found.
    RunFeatureTests(t, &I{})
}

Now to execute tests, run go test as you usually would:

go test -v ./examples/...

#+RESULTS[09983640e601c21bb77c67e7a795b670b2136888]:

=== RUN Test
/home/kate/workspace/go/src/github.com/kat-co/gorkin/examples/features/steps <nil>
Processing: "example-feature.feature".
Scenario: A User Visits the gorkin Site
visit the gorkin site here...
--- PASS: Test (0.00 seconds)
	example_test.go:33: user should see 3
PASS
ok  	github.com/kat-co/gorkin/examples/features/steps	0.001s

You can also run gorkin which is a wrapper around “go test ./features/steps/…”

More complicated examples can be found in gorkin’s own test-suite under the “features” directory.

Where do we go from here?

I built gorkin to explore the Cucumber concept. Because of this, not every Cucumber feature is supported. I’ve opened this package to the public because I’d like some feedback from the Go community on whether this is something we need.