@cepharum/contextual-gherkin

Contextual Gherkin

License

MIT

Install

In a project, add this package as a development dependency.

npm i -D @cepharum/contextual-gherkin gherkin-testcafe

Next, integrate this package with your application's E2E testing following these steps:

1. Include package's files on invoking test runner:
   Make sure to include package's step definitions on invoking E2E tests through gherkin-testcafe in your package.json file's scripts section like this:

   "scripts": {
     "test:e2e": "gherkin-testcafe chrome:headless node_modules/@cepharum/contextual-gherkin/steps/**/*.js --param-type-registry-file ./node_modules/@cepharum/contextual-gherkin/steps/types.js tests/e2e/**/*.js tests/e2e/**/*.feature"
   }
   

   Arguments to gherkin-testcafe are:

   • chrome:headless - the browsers to use
   • node_modules/@cepharum/contextual-gherkin/steps/**/*.js - selecting step definitions of this package
   • --param-type-registry-file ./node_modules/@cepharum/contextual-gherkin/steps/types.js - selecting parameter type registry for custom cucumber expressions to work
   • tests/e2e/**/*.js - selecting step definitions of your application to be tested
   • tests/e2e/**/*.feature - selecting all the Gherkin files of your application to be tested

2. Configure test controller to work in context of your application:
   Set up some common preparation step to inject this package's library into the controller running the tests for your application, e.g. in file tests/e2e/steps/setup.js:

   const { Before } = require( "@cucumber/cucumber" );
   const { ContextualGherkin } = require( "@cepharum/contextual-gherkin" );
   
   Before( t => {
     ContextualGherkin( t, { 
       selectors: { ... },
       aliases: [],
       ...
     } );
   } );
   

   Adjust that configuration object according to your application.

3. Enable your IDE's code assisting:
   Optional: Make sure your IDE is picking up this package's step definitions for code assist. In Jetbrains IDE such as PhpStorm or WebStorm:

   • open Project Explorer
   • expand the node_modules folder
   • expand @cepharum folder
   • right-click on contextual-gherkin folder and check "Include Javascript files" option.

After these prerequisites you can include contextual phrases in your Gherkin test cases, e.g. in a file like tests/e2e/dashboard/basic.feature:

Feature Navigation view
  Scenario basic elements
    Given I open the application
    Then there is a button labelled "Login"
    When I click on it
    Then there is a label reading "Please enter your username"
    And there is a button labelled "Send"
    When I click on this button
    Then the label reads "Your username is required"

In this example scenario, all but the first three lines represent contextual phrases as implemented by this package, so you don't have to implement them for your application. Just focus on those phrases that are specific to your application.

Language

This package is implementing a specific language suitable for flexibly describing a huge amount of use cases to be tested. This language is based on certain words and phrases and understanding them is essential to benefitting from this package.

Special words and phrases

there is ... / there are ...

These phrases are meant to start a global search for matching elements thus breaking out of the context it is used in.

Example:

Given there are three buttons
And there are labels

This expresses the assumption of having three buttons and some labels somewhere on current page. They don't have to do anything with each other.

it / they

The keywords it and they are referring to the results of the most recent search for any element.

Example:

Given there is a button   
And it is enabled

This expresses the global assumption that there is at least one button which is enabled.

the/this/these X

The keywords this and these are used in combination with a name of some elements' common type to refer to the results of the most recent search for that given type of elements.

Example:

Given there are buttons in red 
And there are buttons in blue
And there are labels
And these buttons are enabled

This is expressing the assumption that there are buttons in red, buttons in blue, some labels in addition to those buttons and that the blue buttons are enabled.

that/those X

The keywords that and those are used in combination with a name of some elements' common type to refer to the results of the second-most recent search for that given type of elements.

Example:

Given there are buttons in red 
And there are buttons in blue
And there are labels
And those buttons are enabled

This is expressing the assumption that there are buttons in red, buttons in blue, some labels in addition to those buttons and that the red buttons are enabled.

the latter / the latter X

The phrase the latter is referring to the results of the most recent search for any element. When combined with a type of elements, it is referring to the results of the most recent search for that particular type of element.

Example:

Given there are buttons in red 
And there are buttons in blue
And there are labels
And the latter have a green frame

This is expressing the assumption that there are buttons in red, buttons in blue, some labels in addition to those buttons and that every label has a green frame.

Given there are buttons in red 
And there are buttons in blue
And there are labels
And the latter buttons have a green frame

This is expressing the assumption that there are buttons in red, buttons in blue, some labels in addition to those buttons and that every blue button has a green frame.

the former / the former X

The phrase the former is referring to the results of the second-most recent search for any element. When combined with a type of elements, it is referring to the results of the second-most recent search for that particular type of element.

Example:

Given there are buttons in red 
And there are buttons in blue
And there are labels
And the former have a green frame

This is expressing the assumption that there are buttons in red, buttons in blue, some labels in addition to those buttons and that every blue buttons has a green frame.

Given there are buttons in red 
And there are buttons in blue
And there are labels
And the former buttons have a green frame

This is expressing the assumption that there are buttons in red, buttons in blue, some labels in addition to those buttons and that every red buttons has a green frame.

no, a and cardinals

Phrases may include quantifiers none, a or some cardinal affecting the way a set of matching elements is processed. none is requiring to have no matches at all. a requires at least one matching element, but accepts multiple elements, too. A cardinal is requiring an explicit number of matches to be found with additional matches being rejected.