A Gherkin preprocessor which reads an annotated Gherkin feature file and omits steps which don't include a specific annotation.
According to the test pyramid, you should cover your product with tests on multiple levels (unit tests, IT, E2E test) to test every piece of your functionality with the most efficient testing method.
However, maintaining full test suites is expensive to maintain and specifications can diverge over time. Every implementation of Cucumber knows the same Gherkin format, which makes it possible to drive all your test suites using the same feature files, solving this problem.
Annotated Gherkin is a small extension to the Gherkin language which allows you to specify which step is relevant to a given testing tool. It looks like this:
Feature: Create a new fooAs a userI want to create a new fooSo that I can extend the list of foosScenario: Create a new fooGiven I have a session authorised to create foosAnd a foo with the ID foo_1 and name FooAnd I'm on the Create Foo screen | uiWhen I create the given fooThen the response code is 201 | apiAnd the response body is a Foo object | apiAnd the Foo Created toast message is visible | uiAnd the given Foo is a member of the Foo List
From the feature file above, we can drive an API test which calls the
POST /loginendpoint to create a session
POST /fooendpoint to create the Foo
GET /foo/allendpoint to see if the created Foo has been added to our Foo List.
For our API tests, navigating to the foo creation screen is irrelevant - the HTTP calls will work anytime if we have the correct session.
We can also drive an end-to-end UI test which opens the browser, and
- Opens the login screen and logs in
- Opens the Create Foo screen
- Submits the Create Foo form
- Checks if our toast message is visible
- Opens the Foo List screen
- Checks the Foo List and see if our new Foo is listed.
For our UI test, checking the HTTP response code and the type is irrelevant.
Instead of writing empty step definitions for the irrelevant steps, or trying to come up with a step text which makes
sense for both mediums, you can preprocess this feature file with
$ annotated-gherkin -m ui create-foo.feature Feature: Create a new foo As a user I want to create a new foo So that I can extend the list of foos Scenario: Create a new foo Given I have a session authorised to create foos Given a foo with the ID foo_1 and name Foo Given I'm on the Create Foo screen When I create the given foo Then the Foo Created toast message is visible Then the given Foo is a member of the Foo List $ annotated-gherkin -m api create-foo.feature Feature: Create a new foo As a user I want to create a new foo So that I can extend the list of foos Scenario: Create a new foo Given I have a session authorised to create foos Given a foo with the ID foo_1 and name Foo When I create the given foo Then the response code is 201 Then the response body is a Foo object Then the given Foo is a member of the Foo List
Then you have two standard feature files which you can pass to Cucumber (or even Robot Framework) and run the suite without any noise from the other tests.
Usage: annotated-gherkin [options] <FILE> Preprocess an annotated gherkin file into a regular gherkin file by stripping irrelevant steps. If no tags are specified with -m, then all steps which have an annotation like " | tag" at the end of the step will be dropped from the output gherkin file. If a tag is specified, staps with the given tag will remain, with the annotation removed. Options: -V, --version output the version number -o, --output <FILE> write the Robot Framework version to the given file. Default is the standard output -m, --match <TAG> specify comma-separated list of annotations which should not be dropped from the output gherkin (by default , all annotated sentences are dropped) -h, --help output usage information
The package exports the
annotatedGherkin synchronous function, which takes a Gherkin file's content as string and a
configuration object. It returns the content of the decluttered feature file.
Currently there is one option:
match: Array<String>- A list of annotations which should be preserved. If empty, all annotated steps will be omitted.
The package exports a getter NodeJS Transform stream which applies annotatedGherkin to the incoming sources (vinyls).
The getter takes the
options object as its single parameter.
The following example runs a feature file's UI-specific steps in Robot Framework:
const stream: annotatedGherkin =const stream: gherkin2robot =const exec =const gulp =const log =gulpgulpgulp
Running the test suite
To run the tests, robot framework and
diff needs to be available on
$PATH. The test suite can be run with