From f3b7331ceacbb3e169b9a1d0008135d65d536925 Mon Sep 17 00:00:00 2001 From: gedi Date: Sun, 30 Apr 2017 20:20:00 +0300 Subject: [PATCH] updates documentation in README --- LICENSE | 2 +- Makefile | 2 +- README.md | 148 +++++++++++++++++++++++++++++++++--------------------- godog.go | 3 -- 4 files changed, 94 insertions(+), 61 deletions(-) diff --git a/LICENSE b/LICENSE index 3da1447..caae6cf 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The three clause BSD license (http://en.wikipedia.org/wiki/BSD_licenses) -Copyright (c) 2015-2016, DataDog.lt team +Copyright (c) 2015-2017, DATA-DOG team All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/Makefile b/Makefile index 65ea931..9ceeaee 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ test: @golint github.com/DATA-DOG/godog @golint github.com/DATA-DOG/godog/cmd/godog go vet ./... - go test + go test -race godog -f progress -c 4 gherkin: diff --git a/README.md b/README.md index 706799d..57f7564 100644 --- a/README.md +++ b/README.md @@ -8,26 +8,27 @@ **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](https://github.com/DATA-DOG/godog/blob/master/CHANGELOG.md) +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 core member of [cucumber team](https://github.com/cucumber). -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][behat] and [cucumber][cucumber] and is based on cucumber [gherkin3 parser][gherkin]. -**Godog** does not intervene with the standard **go test** command and its +**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. It uses go +**Godog** acts similar compared to **go test** command, by using go compiler and linker tool in order to produce test executable. Godog -contexts needs to be exported same as Test functions for go test. +contexts need to be exported the same way as **Test** functions for go +tests. **Godog** ships gherkin parser dependency as a subpackage. This will ensure that it is always compatible with the installed version of godog. @@ -58,16 +59,16 @@ business goal in mind at all times. When automated testing is this much fun, teams can easily protect themselves from costly regressions. -### Install +## Install go get github.com/DATA-DOG/godog/cmd/godog -### Example +## Example The following example can be [found here](/examples/godogs). -#### Step 1 +### Step 1 Given we create a new go package **$GOPATH/src/godogs**. From now on, this is our work directory `cd $GOPATH/src/godogs`. @@ -89,14 +90,11 @@ Feature: eat godogs 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. - **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 +### 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 @@ -126,7 +124,7 @@ pass successfully. Since we need a working implementation, we may start by implementing only what is necessary. -#### Step 3 +### Step 3 We only need a number of **godogs** for now. Lets keep it simple. @@ -140,7 +138,7 @@ var Godogs int func main() { /* usual main func */ } ``` -#### Step 4 +### Step 4 Now lets implement our step definitions, which we can copy from generated console output snippets in order to test our feature requirements: @@ -190,32 +188,49 @@ Now when you run the `godog` again, you should see: ![Passed suite](/screenshots/passed.png?raw=true) -**Note:** we have hooked to **BeforeScenario** event in order to reset state. You may hook into -more events, like **AfterStep** to test against an error and print more details about the error -or state before failure. Or **BeforeSuite** to prepare a database. +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. -#### Running Godog with go test +By now, you should have figured out, how to use **godog**. Another advice +is to make steps orthogonal, small and simple to read for an 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. -There was a question asked whether it is possible to run **godog** from -**go test** command. And the answer is yes. You can run it using go -[TestMain](https://golang.org/pkg/testing/#hdr-Main) func available since -go 1.4. In this case it is not necessary to have **godog** command -installed. See the following example: +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 + +- [how to use godog by semaphoreci](https://semaphoreci.com/community/tutorials/how-to-use-godog-for-behavior-driven-development-in-go) +- see [examples](https://github.com/DATA-DOG/godog/tree/master/examples) + +### Documentation + +See [godoc][godoc] for general API details. +See **.travis.yml** for supported **go** versions. +See `godog -h` for general command options. + +See implementation examples: + +- [rest API server](/examples/api) +- [rest API with Database](/examples/db) +- [godogs](/examples/godogs) + +## FAQ + +### Running Godog with go test + +You may integrate running **godog** in your **go test** command. You can +run it using go [TestMain](https://golang.org/pkg/testing/#hdr-Main) func +available since **go 1.4**. In this case it is not necessary to have +**godog** command installed. See the following example: ``` go -/* file: $GOPATH/src/godogs/godogs_test.go */ -package main - -import ( - "os" - "testing" - "time" - - "github.com/DATA-DOG/godog" -) - func TestMain(m *testing.M) { - status := godog.RunWithOptions("godogs", func(s *godog.Suite) { + status := godog.RunWithOptions("godog", func(s *godog.Suite) { FeatureContext(s) }, godog.Options{ Format: "progress", @@ -230,31 +245,42 @@ func TestMain(m *testing.M) { } ``` -### References and Tutorials +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: -- [how to use godog by semaphoreci](https://semaphoreci.com/community/tutorials/how-to-use-godog-for-behavior-driven-development-in-go) +``` go +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 + } + } + status := RunWithOptions("godog", func(s *Suite) { + SuiteContext(s) + }, Options{ + Format: format, + Paths: []string{"features"}, + }) -### Documentation + if st := m.Run(); st > status { + status = st + } + os.Exit(status) +} +``` -See [godoc][godoc] for general API details. -See **.travis.yml** for supported **go** versions. -See `godog -h` for general command options. +Now when running `go test -v` it will use **pretty** format. -See implementation examples: - -- [rest API server](/examples/api) -- [rest API with Database](/examples/db) -- [godogs](/examples/godogs) - -### FAQ - -#### Configure common options for godog CLI +### 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 +### Testing browser interactions **godog** does not come with builtin packages to connect to the browser. You may want to look at [selenium](http://www.seleniumhq.org/) and @@ -266,13 +292,23 @@ components: 2. You may wish to have [goquery](https://github.com/PuerkitoBio/goquery) in order to work with HTML responses like with JQuery. -### Contributions +### 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. + +## 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 +## License **Godog** is licensed under the [three clause BSD license][license] diff --git a/godog.go b/godog.go index 80d8fd0..a8a2984 100644 --- a/godog.go +++ b/godog.go @@ -30,9 +30,6 @@ Example: 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.