README
¶
Godog
Godog is an open source behavior-driven development framework for go programming language. 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 gherkin specification.
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 builds all package sources to a single main package file and replaces main func with it's own and runs the build to test described application behavior in feature files. Production builds remains clean without any overhead.
Install
go get github.com/DATA-DOG/godog/cmd/godog
Example
Imagine we have a godog cart to serve godogs for dinner. At first, we describe our feature:
# file: /tmp/godog/godog.feature
Feature: eat godogs
In order to be satiated
As an user
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.
If you run godog godog.feature inside the /tmp/godog directory.
You should see that the steps are undefined:
/* file: /tmp/godog/godog.go */
package main
type GodogCart struct {
reserve int
}
func (c *GodogCart) Eat(num int) { c.reserve -= num }
func (c *GodogCart) Available() int { return c.reserve }
func main() { /* usual main func */ }
If you run godog godog.feature inside the /tmp/godog directory.
You should see that the steps are undefined.
Now lets describe all steps to test the application behavior:
/* file: /tmp/godog/godog_test.go */
package main
import (
"fmt"
"github.com/DATA-DOG/godog"
"github.com/DATA-DOG/godog/gherkin"
)
func (c *GodogCart) resetReserve(*gherkin.Scenario) {
c.reserve = 0
}
func (c *GodogCart) thereAreNumGodogsInReserve(args ...*godog.Arg) error {
c.reserve = args[0].Int()
return nil
}
func (c *GodogCart) iEatNum(args ...*godog.Arg) error {
c.Eat(args[0].Int())
return nil
}
func (c *GodogCart) thereShouldBeNumRemaining(args ...*godog.Arg) error {
if c.Available() != args[0].Int() {
return fmt.Errorf("expected %d godogs to be remaining, but there is %d", args[0].Int(), c.Available())
}
return nil
}
func godogCartContext(s godog.Suite) {
c := &GodogCart{}
// each time before running scenario reset reserve
s.BeforeScenario(c.resetReserve)
// register steps
s.Step(`^there are (\d+) godogs?$`, c.thereAreNumGodogsInReserve)
s.Step(`^I eat (\d+)$`, c.iEatNum)
s.Step(`^there should be (\d+) remaining$`, c.thereShouldBeNumRemaining)
}
Now when you run the godog godog.feature again, you should see:
Documentation
See godoc for general API details. See .travis.yml for supported go versions.
The public API is stable enough, but it may break until 1.0.0 version, see godog --version.
FAQ
Q: Where can I configure common options globally?
A: You can't. Alias your common or project based commands: alias mygodog="godog --format=progress"
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 a behavior-driven development framework, a tool to describe your application based on the behavior and run these specifications. The features are described by a human-readable gherkin language.
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 builds all package sources to a single main package file and replaces main func with it's own and runs the build to test described application behavior in feature files. Production builds remains clean without any overhead.
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 the above description is taken from it's documentation.
Index ¶
- Constants
- Variables
- func Build() ([]byte, error)
- func RegisterFormatter(name, description string, f Formatter)
- type Arg
- func (a *Arg) Bytes() []byte
- func (a *Arg) DataTable() *gherkin.DataTable
- func (a *Arg) DocString() *gherkin.DocString
- func (a *Arg) Float32() float32
- func (a *Arg) Float64() float64
- func (a *Arg) Int() int
- func (a *Arg) Int16() int16
- func (a *Arg) Int32() int32
- func (a *Arg) Int64() int64
- func (a *Arg) Int8() int8
- func (a *Arg) String() string
- type Formatter
- type Regexp
- type StepDef
- type StepHandler
- type Suite
Constants ¶
const Version = "v0.1.0"
Version of package - based on Semantic Versioning 2.0.0 http://semver.org/
Variables ¶
var ErrUndefined = fmt.Errorf("step is undefined")
ErrUndefined is returned in case if step definition was not found
Functions ¶
func Build ¶
Build creates a runnable Godog executable file from current package source and test source files.
The package files are merged with the help of go/ast into a single main package file which has a custom main function to run test suite features.
Currently, to manage imports we use "golang.org/x/tools/imports" package, but that may be replaced in order to have no external dependencies
func RegisterFormatter ¶
RegisterFormatter registers a feature suite output Formatter as the name and descriptiongiven. Formatter is used to represent suite output
Types ¶
type Arg ¶
type Arg struct {
// contains filtered or unexported fields
}
Arg is an argument for StepHandler parsed from the regexp submatch to handle the step.
In future versions, it may be replaced with an argument injection toolkit using reflect package.
func StepArgument ¶
func StepArgument(value interface{}) *Arg
StepArgument func creates a step argument. used in cases when calling another step from within a StepHandler function.
func (*Arg) DataTable ¶
func (a *Arg) DataTable() *gherkin.DataTable
DataTable converts an argument to *gherkin.DataTable node
func (*Arg) DocString ¶
func (a *Arg) DocString() *gherkin.DocString
DocString converts an argument to *gherkin.DocString node
type Formatter ¶
type Formatter interface {
Feature(*gherkin.Feature, string)
Node(interface{})
Failed(*gherkin.Step, *StepDef, error)
Passed(*gherkin.Step, *StepDef)
Skipped(*gherkin.Step)
Undefined(*gherkin.Step)
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 RegisterFormatter function call
type Regexp ¶
type Regexp interface{}
Regexp is an unified type for regular expression it can be either a string or a *regexp.Regexp
type StepDef ¶
type StepDef struct {
Args []*Arg
Handler StepHandler
Expr *regexp.Regexp
}
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 StepHandler ¶
StepHandler is a func to handle the step
The handler receives all arguments which will be matched according to the Regexp which is passed with a step registration.
The error in return - represents a reason of failure. All consequent scenario steps are skipped.
Returning signals that the step has finished and that the feature runner can move on to the next step.
type Suite ¶
type Suite interface {
Run()
Step(expr Regexp, h StepHandler)
// suite events
BeforeSuite(f func())
BeforeScenario(f func(interface{}))
BeforeStep(f func(*gherkin.Step))
AfterStep(f func(*gherkin.Step, error))
AfterScenario(f func(interface{}, error))
AfterSuite(f func())
}
Suite is an interface which allows various contexts to register steps and event handlers.
When running a test suite, this interface 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.
Source Files
Directories