gorkin

#+TITLE: gorkin
#+AUTHOR: Katherine Cox-Buday

[[https://godoc.org/github.com/kat-co/gorkin/gorkin][https://godoc.org/github.com/kat-co/gorkin/gorkin?status.svg]]

gorkin is an experimental implementation of [[https://cucumber.io/][cucumber]] for [[https://golang.org/][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:

#+BEGIN_SRC feature :cached yes :exports code :tangle examples/features/example-feature.feature
  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.
#+END_SRC

And a corresponding gorkin test might look something like this:

#+BEGIN_SRC go :cached yes :exports code :tangle examples/features/steps/example_test.go
    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{})
    }
#+END_SRC

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

#+BEGIN_SRC sh :export both :results output replace
  go test -v ./examples/...
#+END_SRC

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