updates documentation in README

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

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:

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
+We have hooked to **BeforeScenario** event in order to reset application
-more events, like **AfterStep** to test against an error and print more details about the error
+state before each scenario. You may hook into more events, like
-or state before failure. Or **BeforeSuite** to prepare a database.
+**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
+When steps are orthogonal and small, you can combine them just like you do
-**go test** command. And the answer is yes. You can run it using go
+with Unix tools. Look how to simplify or remove ones, which can be
-[TestMain](https://golang.org/pkg/testing/#hdr-Main) func available since
+composed.
-go 1.4. In this case it is not necessary to have **godog** command
+
-installed. See the following example:
+### 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.
+Now when running `go test -v` it will use **pretty** format.
-See **.travis.yml** for supported **go** versions.
-See `godog -h` for general command options.
 
-See implementation examples:
+### Configure common options for godog CLI
-
-- [rest API server](/examples/api)
-- [rest API with Database](/examples/db)
-- [godogs](/examples/godogs)
-
-### FAQ
-
-#### 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]
 

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.