It's a Behaviour Driven Development (BDD) tests generator for Golang.
It accepts a *.feature
Cucumber/Gherkin file and generates a test boilerplate. All that remains is to change the tests a little. The generator supports go generate
and go test
for generated tests.
The generator is very customizable, it is possible to customize an output for any golang testing framework or even for another language.
Feature: Application command line tool
Scenario Outline: User wants to see usage information
When the application is started with <flag>
Then usage should be printed <printed>
And exit status should be <exit_status>
Examples:
| <flag> | <exit_status> | <printed> |
| --help | 0 | true |
| -help | 0 | true |
| -invalid | 1 | false |
Then this generator writes a golang output (gerkingen readme.feature > readme.feature_test.go
):
func TestApplicationCommandLineTool(t *testing.T) {
t.Parallel()
t.Run("User wants to see usage information", func(t *testing.T) {
t.Parallel()
type testCase struct {
Flag string `field:"<flag>"`
ExitStatus int `field:"<exit_status>"`
Printed bool `field:"<printed>"`
}
testCases := map[string]testCase{
"--help_0_true": {"--help", 0, true},
"-help_0_true": {"-help", 0, true},
"-invalid_1_false": {"-invalid", 1, false},
}
for name, testCase := range testCases {
testCase := testCase
t.Run(name, func(t *testing.T) {
t.Parallel()
// When the application is started with <flag>.
// Then usage should be printed <printed>.
// And exit status should be <exit_status>.
})
}
})
}
Example implementation:
t.Run(name, func(t *testing.T) {
t.Parallel()
// When flag <flag> is provided.
arguments := []string{testCase.Flag}
// Then usage should be printed <printed>.
var output string
output, exitStatus = runApp(t, arguments)
assert.Equal(t, testCase.Printed, strings.Contains(output, "usage"))
// And exit status should be <exit_status>.
assert.Equal(t, testCase.ExitStatus, exitStatus)
})
See internal/app/app.feature and internal/app/app_test.go.
- Simplified template is set by default. In order to use the default template from the previous versions, provide the following flag
-template @/std.struct.v1.go.tmpl
. - All tests will have
t.Parallel
by default. This behaviour can be disabled by providing the flag-disable-go-parallel
.
Latest DEB and RPM packages are available on the releases page.
# Install the package using HomeBrew.
brew install hedhyw/gherkingen/gherkingen
# Check that the generator is working.
gherkingen -help
Download latest archive *.tar.gz
for your target platform from the releases page and extract it to /usr/local/bin/gherkingen
. Add this path to PATH
environment.
Example flow:
# Check the signature of a downloaded archive and the signature in the file task_checksums.txt from the release page.
# Remove old binaries.
rm -rf /usr/local/gherkingen
# Restore folder structure.
mkdir -p /usr/local/gherkingen
# Extract archive to target path.
tar -C /usr/local/gherkingen -xzf DOWNLOAD_ARCHIVE.TAR.GZ
# Add `/usr/local/gherkingen` to PATH environment variable.
export PATH=/usr/local/gherkingen:$PATH
# Check that the generator is working.
gherkingen -help
go install github.com/hedhyw/gherkingen/v3/cmd/gherkingen@latest
# Notice: gherkingen -version will return "unknown" version.
git clone [email protected]:hedhyw/gherkingen.git
cd gherkingen
make build
cp ./bin/gherkingen /usr/local/bin
chmod +x /usr/local/bin
The extension for VS-Code that helps to generate Behaviour Driven Development (BDD) boilerplate Golang tests. It uses docker to run gherkingen
.
https://marketplace.visualstudio.com/items?itemName=hedhyw.golang-gherkingen&ssr=false#overview
Launch VS Code Quick Open (Ctrl+P or Cmd+P), paste the following command, and press enter: ext install hedhyw.golang-gherkingen
.
Usage of the extension (in any .feature file):
- Open the command palette (Ctrl+Shift+P or Cmd+Shift+P) and search for "Go: Generate BDD Golang test".
- Or, click the button "Generate BDD Golang test" in the editor's menu.
For generating test output, simply run:
gherkingen EXAMPLE.feature
gherkingen \
-format go \
-template my_template.tmpl \
EXAMPLE.feature
gherkingen -list
gherkingen --help
Usage of gherkingen [FEATURE_FILE]:
-disable-go-parallel
disable execution of tests in parallel
-format string
output format: autodetect, json, go, raw (default "autodetect")
-go-parallel
add parallel mark (deprecated, enabled by default) (default true)
-help
print usage
-list
list internal templates
-package string
name of the generated package (default "generated_test")
-permanent-ids
The same calls to the generator always produces the same output
-template string
template file (default "@/std.simple.v1.go.tmpl")
-version
print version
Docker image: https://hub.docker.com/r/hedhyw/gherkingen
Running gherkingen in docker, <RELATIVE_PATH_TO_FEATURE_FILE>
is
a path to a feature file relatively to the current directory.
docker run --rm -it --read-only --network none \
--volume $PWD:/host/:ro \
hedhyw/gherkingen:latest \
-- /host/<RELATIVE_PATH_TO_FEATURE_FILE>
Passing arguments:
# Any command-line tool arguments also can be used.
# Example:
docker run --rm -it --read-only --network none \
hedhyw/gherkingen:latest -list
You can provide your own template, it can be based on internal/assets/std.struct.v1.go.tmpl. In the command-line tool specify the template
using -template
flag: gherkingen -template example.tmpl raw example.feature
It is possible to integrate the generator with any BDD-testing fraemwork. Feel free to create a pull request for supporting templates for them. For this:
- Create a template
internal/assets/SOME_NAME.go.tmpl
. - Add it to the test
TestOpenTemplate
in the file internal/assets/assets_test.go. - Check:
make lint check.generate test
. - Commit&Push, create a PR.
Templates are very customizable, so you can even generate non-golang code. In the command-line tool specify raw
format using -format
flag and your template using -template
flag:
gherkingen -format raw -template example.tmpl example.feature
.
Useful resources:
Resource | Link |
---|---|
Golang template documentation | text/template |
Root template object struct documentation | TemplateData |
Example template | std.struct.v1.go.tmpl |
Example json representation of a root template object | readme.feature.json |
There is a way to return a json representation of the root object TemplateData
for your feature, for this run gherkingen -format json <EXAMPLE.feature>
.
Any field of the root object can be used directly, example: {{ .PackageName }}
.
Exclude the rule thelper
for scenarios in the configuration .golangci.yaml:
issues:
fix: true
exclude-rules:
- linters:
- thelper
source: "^.*f\\.Scenario.*$"
- The library and generator are under MIT Lecense.
- The gopher is under Creative Commons Attribution 3.0 license. It was originally designed by Renรฉe French and redrawed by me.