• Stars
    star
    72
  • Rank 438,337 (Top 9 %)
  • Language
    Go
  • License
    MIT License
  • Created almost 3 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Behaviour Driven Development tests generator for Golang

gherkingen

Version Build Status Go Report Card Coverage Status Mentioned in Awesome Go

It's a Behaviour Driven Development (BDD) tests generator for Golang.

Gopher Gherkingen BDD testing 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.

What is for?

Simple example

Given feature [reference]:

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)
})

More advanced example

See internal/app/app.feature and internal/app/app_test.go.

Version 3 changes

  1. 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.
  2. All tests will have t.Parallel by default. This behaviour can be disabled by providing the flag -disable-go-parallel.

Install

Package

Latest DEB and RPM packages are available on the releases page.

MacOS/Linux HomeBrew

# Install the package using HomeBrew.
brew install hedhyw/gherkingen/gherkingen

# Check that the generator is working.
gherkingen -help

Standalone Binary

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

go install github.com/hedhyw/gherkingen/v3/cmd/gherkingen@latest
# Notice: gherkingen -version will return "unknown" version.

Source

git clone [email protected]:hedhyw/gherkingen.git
cd gherkingen
make build
cp ./bin/gherkingen /usr/local/bin
chmod +x /usr/local/bin

Visual Studio Code extension

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.

Usage

Simple usage

For generating test output, simply run:

gherkingen EXAMPLE.feature

More advanced usage

Generating test output with custom options

gherkingen \
    -format go \
    -template my_template.tmpl \
    EXAMPLE.feature

Listing internal templates

gherkingen -list

Help

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

Running in docker

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

Output customization

Custom templates

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

Frameworks support

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:

  1. Create a template internal/assets/SOME_NAME.go.tmpl.
  2. Add it to the test TestOpenTemplate in the file internal/assets/assets_test.go.
  3. Check: make lint check.generate test.
  4. Commit&Push, create a PR.

Language support

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.

Creating templates

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 }}.

golangci-lint thelper warning

Exclude the rule thelper for scenarios in the configuration .golangci.yaml:

issues:
  fix: true
  exclude-rules:
    - linters:
        - thelper
      source: "^.*f\\.Scenario.*$"

License

More Repositories

1

rex

Flexible regular expressions constructor for Golang.
Go
194
star
2

json-log-viewer

Interactive viewer for JSON logs.
Go
71
star
3

spice3f5

Add cmake to spice3f5 for build in linux or windows. SPICE is a general-purpose circuit simulator with several built-in semiconductor device models. SPICE was developed at the Electronics Research Laboratory of the University of California, Berkeley.
C
36
star
4

BrillouinZones

Programs for constructing Brillouin zones in three- and two-dimensional space.
Python
28
star
5

otelinji

OpenTelemetry auto-instrumentation tool for Golang. It automatically injects OpenTelemetry blocks.
Go
16
star
6

go-import-lint

Golang source code analyzer that checks imports order. It verifies that standard, current package, and vendor imports are separated by a line.
Go
16
star
7

Go-Serial-Detector

A go library for determining active serial ports.
Go
14
star
8

jsoncjson

JSONC (json with comments) to JSON translator for Golang.
Go
11
star
9

Directory

Directory & File Chooser dialog for Android
Java
6
star
10

semerr

A way of dealing with Golang errors
Go
6
star
11

HyperFractal

A three-dimensional fractal animation generator.
C++
6
star
12

DinoMega8

Firmware of the Dino game for microcontroller ATmega8
C
4
star
13

DielectricBreakdown

Source codes of programs for a designed device. The device measures the parameters of dielectric films.
C
3
star
14

CExpr

Math Complex Expression Compiler
Java
3
star
15

go-ipbot

Hello-Telegram-Bot that sends the IP address of a remote machine
Go
3
star
16

beehivedlna

Webpage
CSS
2
star
17

LogNotifierBot

Bot for the telegram that sends new messages from sshd/auth.log.
Java
2
star
18

Ocmoxa-Vietblog

The blog with Vietnamese stories for language learners. ๐ŸŒด ๐Ÿ‡ป๐Ÿ‡ณ ๐Ÿฅฅ
HTML
2
star
19

go-psw

A tiny secure-random password generator
Go
2
star
20

telegram-pictionary-it

Telegram MiniApp bot game in which players can draw and guess pictures
Makefile
2
star
21

simple-4bit-cpu

Vivado project with example of simple 4bit CPU
Verilog
2
star
22

Vietnamese-Notes

The blog with brief Vietnamese language notes and an awesome Vietnamese resources list
HTML
1
star
23

Right-Angle-Build

Right Angle Website
HTML
1
star
24

telegram-pictionary-it-backend

Backend for "Pictionary It telegram" bot
Go
1
star
25

telegram-mic-guitar-tuner

@micguitartunerbot is a Telegram Mini App that helps to tune guitars
JavaScript
1
star
26

bdd-resizer-example

JPEG image resizer server for a Golang article
Go
1
star
27

go-tarantool-structure

Go
1
star
28

ippserver-docker

A small docker image which pretends to be a printer.
Makefile
1
star
29

telegram-pictionary-it-frontend

Frontend for "Pictionary It telegram" bot
JavaScript
1
star
30

vscode-golang-gherkingen

VS-Code extension to generate Golang Behaviour Driven Development (BDD) tests
TypeScript
1
star
31

homebrew-main

Collection of homebrews
Ruby
1
star