gherkin-testcafe

Run testcafe tests with gherkin syntax

Usage no npm install needed!

<script type="module">
  import gherkinTestcafe from 'https://cdn.skypack.dev/gherkin-testcafe';
</script>

README

gherkin-testcafe

Run testcafe tests with gherkin syntax

Table of contents

  1. What it does
  2. Installation
  3. Upgrading from previous version
  4. CLI Usage
  5. Programming interface
  6. Writing step definitions
  7. Supported gherkin features and limitations
    1. Tags
    2. Cucumber Expressions
    3. Hooks
      1. Before and After
      2. BeforeAll and AfterAll
    4. Data tables
  8. Using typescript and ESnext features
  9. Contributing
    1. Commits
    2. Releases

What it does

TestCafé is a tool to write tool to automate end-to-end test fo websites. This package provides a compatibility layer to support of BDD-style tests to be run with TestCafé using the Gherkin syntax. Please note that there seems to be a plan to officially support Gherkin syntax in TestCafé. Once official support is established, this package will be abandoned.

Installation

Install gherkin-testcafe and cucumber1 via npm or yarn:

npm i gherkin-testcafe @cucumber/cucumber

or

yarn add gherkin-testcafe @cucumber/cucumber

You may also install gherkin-testcafe globally in order to be able to use the CLI without npx.

1 This package internally uses Cucumber.js to parse step definitions. You will need it to define steps (see Writing step definitions).

Upgrading from version 1.x

With TestCafé version 2.0, this package has introduced some breaking changes to it's API. These changes help this package be more future-proof in terms of upcoming features.

When upgrading this package from version 1 to version 2, keep in mind, that the following things have changed:

  • CLI interface is now passed through from TestCafé itself. So some options have changed:
    • --specs, --steps, -s and -d option no longer exist. Please define all the files as regular test files. Also note, that all feature files have to have .feature file ending.
    • -b option is now a shorthand for --list-browsers (as it is in the regular testcafe CLI). Define browsers like you would in testcafe. See also CLI usage.
  • Step parameters are now passed to the step implementation as an array. Code needs to be refactored in the following way:
    - Given(/some (.+) text (.+) with (.+) capturing (.+) groups/, async (t, param1, param2, param 3, param 4) => {});
+ Given(/some (.+) text (.+) with (.+) capturing (.+) groups/, async (t, [param1, param2, param 3, param 4]) => {});
  • BeforeAll and AfterAll hooks now run before/ after a feature, not a scenario. See also BeforeAll and AfterAll.
  • The same prohibition for multiple method calls as for testcafe@1.0.0 applies. See also testcafe@1.0.0 release notes.
  • Legacy Docker support dropped

CLI usage

Use the gherkin-testcafe just like you use TestCafé's CLI. Just replace testcafe by gherkin-testcafe and load all JS and feature files:

gherkin-testcafe firefox,IE tests/**/*.js tests/**/*.feature

Use --help command to see all options:

gherkin-testcafe --help

All TestCafé CLI options are supported.

Additionally, you can specify:

  • tags to run (see Tags):

    The --tags parameter can take a list of tags to filter scenarios in (or out) of the test run.

    • including tag:

        gherkin-testcafe firefox tests/**/*.js tests/**/*.feature --tags @TAG

      This runs all scenarios that have @TAG

    • excluding tag:

        gherkin-testcafe firefox tests/**/*.js tests/**/*.feature --tags ~@TAG

      This runs all scenarios that don't have @TAG

    • list of tags:

        gherkin-testcafe firefox tests/**/*.js tests/**/*.feature --tags @TAG1,@TAG2

      This runs all scenarios that have @TAG1 or @TAG2

        gherkin-testcafe firefox tests/**/*.js tests/**/*.feature --tags @TAG1,~@TAG2

      This runs all scenarios that have @TAG1 and not @TAG2

    • and operation:

        gherkin-testcafe firefox tests/**/*.js tests/**/*.feature --tags "@TAG1 and @TAG2"

      This runs all scenarios that have @TAG1 and @TAG2

        gherkin-testcafe firefox tests/**/*.js tests/**/*.feature --tags "@TAG1 and ~@TAG2, @TAG2 and ~@TAG1"

      This runs all scenarios that have either @TAG1 or @TAG2, not both

  • custom parameter types, (see Cucumber Expressions)

      gherkin-testcafe firefox tests/**/*.js tests/**/*.feature --param-type-registry-file ./a-file-that-exports-a-parameter-type-registry.js

Programming interface

To get more fine grained control over the testrun, you can use the programming interface. It is very similar to TestCafé's programming interface. It supports all options of TestCafé's runner class, except it replaces src with steps and specs.

You can use the programming interface almost exactly like TestCafé's. Just replace the import of testcafe by gherkin-testcafe and load all step and spec files:

- const createTestCafe = require('testcafe');
+ const createTestCafe = require('gherkin-testcafe');

module.exports = async () => {
    const testcafe = await createTestCafe();
    const runner = await testcafe.createRunner();
    const remoteConnection = await testcafe.createBrowserConnection();

    return runner
-       .src('test.js')
+       .src(['steps/**/*.js', 'specs/**/*.feature'])
        .browsers([remoteConnection, 'chrome'])
        .run();
};

You can use all other runner methods, that you like as well (e.g. filter, screenshots and reporter).

Writing step definitions

To write step definitions, import Given, When and/ or Then from cucumber2:

import { Given, When, Then } from '@cucumber/cucumber';

Given(/some precondition/, async (t) => {
    // The first argument of Given, When and Then will be a regex that matches the step.
    // The second argument is a function that takes TestCafé's test controller object as a parameter.
});

When(/something (.+) happens/, async (t, params) => {
    // Captured parameters in the step regex will be passed as the second argument to the test implementation.
    // "When Something great happens" will call this function with `["great"]` as `params`.
});

When(/something (.+) and (.+) happens/, async (t, [param1, param2]) => {
    // You can use regular array destructuring to access params directly.
    // "When Something great and awesome happens" will result in `"great"` as `param1` and `"awesome"` as `param2`.
});

Then(/an assertion takes place/, async (t) => {
    // Test code is the same as TestCafé's test function accepts.
    await t.expect(true).ok();
});

Then('use Cucumber Expressions to get {int}, {float}, {word}, {string}, etc', async (t, [intParam, floatParam, singleWordParam, stringParam]) => {
    // You can use "Cucumber Expressions" instead of regex to get the parameters in the desired types.
    // It's also possible to add custom parameter types if needed.
    await t.expect(typeof intParam).eql('number');
});

2 You need to install Cucumber.js as a dependency (see Installation).

It is worth noting, that for the test runner, Given, When and Then are the same thing. You can define

Given(/some step/, async (t) => {
    // Test code
});

and use it as

When some step

Please refer to the examples directory for more examples.

Supported gherkin features and limitations

This package supports a wide range of gherkin features. Most notable features are:

  • Features (Gherkin feature keyword): Will be transformed into a TestCafé fixture.
  • Scenarios (Gherkin scenario keyword): Will be transformed into a TestCafé test.
  • Backgrounds (Gherkin background keyword): Background steps are prepended to Scenario/ Scenario outline steps. Before hooks are run before background steps.
  • Scenario outlines (Gherkin scenario outline and examples keywords): Will transform every example into on TestCafé test.
  • Tags/ Hooks: See Tags and Hooks.
  • Cucumber Expressions

Tags

Scenarios can be tagged using Gherkin's @-notation. The runner can then be configured to filter scenarios to be run based on these tags. The tags will be evaluated such that scenarios that have any of the including tags (begins with @) but none of the excluding tags (begins with ~@) will be run.

Examples:

    runner.tags(['@TAG']) // Will run all scenarios marked with @TAG

    runner.tags(['~@TAG']) // Will run all scenarios that are not marked with @TAG

    runner.tags(['@TAG', '~@OTHER_TAG']) // Will run all scenarios that are marked with @TAG but not with @OTHER_TAG
    
    runner.tags(['@TAG', '@OTHER_TAG']) // Will run all scenarios that are marked with @TAG or with @OTHER_TAG
    
    runner.tags(['@TAG and @OTHERTAG']) // Will run all scenarios that are marked with @TAG and with @OTHER_TAG

Note: Do not set --tags CLI parameter when running tests through the programming interface as it is internally used to pass the selected tags to the gherkin compiler.

Cucumber Expressions

Besides using Regular Expressions, you can also use Cucumber Expressions in your steps, and have support for Optional text, Alternative text and getting parameters in their desired types. The Cucumber built-in parameter types are supported by default.

It's also possible to add custom parameter types by creating a file that exports a cucumberExpressions.ParameterTypeRegistry, and passing this file's path to the CLI with --param-type-registry-file or to the Programming interface with the parameterTypeRegistryFile method.

Example:

  1. Create a ParameterTypeRegistry (e.g. myCustomParamRegistry.js):

    import { ParameterTypeRegistry, ParameterType } from 'cucumber-expressions';

class Color {
    constructor(name) {
        this.name = `${name} color`;
    }
}

const registry = new ParameterTypeRegistry();

registry.defineParameterType(
    new ParameterType(
        'color', // name of the parameter
        /red|blue|yellow/, // regexp used to match
        Color, // the parameter's type
        name => new Color(name) // transformer function
    )
);

module.exports = registry;

  2. Use it in a step:

     When I am searching for the blue color on Google

  3. Retrieve the value in the step implementation:

    When('I am searching for the {color} color on Google', async (t, [color]) => {
    console.log(color.name); // blue color
});

  4. Configure the runner to use your custom ParameterTypeRegistry:

    runner.parameterTypeRegistryFile(require.resolve('./myCustomParamRegistry.js'))

    Note: Do not set --param-type-registry-file CLI parameter when running tests through the programming interface as it is internally used to pass the path of the ParameterTypeRegistry file to the gherkin compiler.

Please refer to the examples folder, and the official Cucumber Expressions documentation for more details.

Hooks

In contrast to Cucumber.js' hooks, they are implemented differently in this package. Hooks in this package are always asynchronous. Instead of taking a callback parameter to end the hook, this package's hooks return a promise. Once this promise fulfills, the hook is considered done. The order of hook execution is not guaranteed to follow any rules. So be careful when using multiple hooks for the same scenario.

Before and After

Before/ After hooks run before or after each test (i.e. scenario). Each hook implementation gets TestCafé's test controller object as a parameter.

import { Before } from '@cucumber/cucumber';

Before('@tag1', async (t) => {
    // do something
    // e.g. write to t.ctx or read from t.fixtureCtx
});

Untagged hooks are run before/ after each test.

BeforeAll and AfterAll

BeforeAll/ AfterAll hooks run before and after each fixture (i.e. feature). Each hook implementation gets TestCafé's fixture context. See Sharing Variables Between Fixture Hooks and Test Code documentation for more details.

import { BeforeAll } from '@cucumber/cucumber';

BeforeAll(async (ctx) => {
    // do something with the context
})

Data tables

When steps have a data table, they are passed an object with methods that can be used to access the data.

  • with column headers
    • hashes: returns an array of objects where each row is converted to an object (column header is the key)
    • rows: returns the table as a 2-D array, without the first row
  • without column headers
    • raw: returns the table as a 2-D array
    • rowsHash: returns an object where each row corresponds to an entry (first column is the key, second column is the value)

see examples section for an example

Using typescript and ESnext features

With gherkin-testcafe, you can use Typescript and ESnext features (like es module import statements) the same way you can use them in regular TestCafé tests. In fact, it actually uses TestCafé's compilers to compile Typescript and ESNext files.

Please refer to TestCafé's Typescript support manual page to see how you can customize compiler options and which compiler options are used by default.

Please make sure not to install @types/cucumber! gherkin-testcafe will provide types for the cucumber module.

Unfortunately, you cannot define your custom parameter types registry file in typescript or with ESnext features.

Contributing

  • The release branch is master.
  • The development branch is develop.

Always create your new branch from develop.

I'd appreaciate if you would use git flow (or follow its naming conventions) but it's not mandatory.

Commits will generally not be accepted if they have not been properly formatted.

Commits

The package has commitizen as a dev dependency. To create the proper commit, use yarn gitcommit and follow the prompts.

Do not hesitate to create an issue if you need help.

Releases

The package has standard-version as a dev dependency. It makes version management pretty easy, as long as commits have been properly formatted (hence the obligation to use commitizen)