Run testcafe tests with gherkin syntax
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.
Install gherkin-testcafe
and cucumber
1 via npm or yarn:
npm i gherkin-testcafe cucumber
or
yarn add gherkin-testcafe cucumber
1 This package internally uses Cucumber.js to parse step definitions. You will need it to define steps (see Writing step definitions).
Use the gherkin-testcafe
package to run test via CLI:
gherkin-testcafe --steps tests/**/*.js --specs tests/**/*.feature --browsers firefox
You can use shorthands:
gherkin-testcafe -d tests/**/*.js -s tests/**/*.feature -b firefox
Out of TestCafé's CLI options a limited amount are supported for this package.
The following options are supported:
Option | Shorthand | Required | Description | Default |
---|---|---|---|---|
specs | s | Required | A space separated list of feature files to run.We use glob to match paths. | N.A. |
steps | d | Required | A space separated list of file paths to load the step definitions from. We use glob to match paths. | N.A. |
browsers | b | Optional | A space separated list of browsers to run the tests in. | chrome:headless |
ports | p | Optional | A space separated list of ports for TestCafé to perform testing on. | 1337,1338 |
skipJsErrors | e | Optional | Make tests not fail when a JS error happens on a page | false |
disablePageReloads | N.A. | Optional | Disable page reloads between tests | false |
quarantineMode | q | Optional | Enable quarantine mode | false |
debugMode | N.A. | Optional | Execute test steps one by one pausing the test after each step | false |
debugOnFail | N.A. | Optional | Enter debug mode when the test fails | false |
speed | N.A. | Optional | Set the speed of test execution (0.01 ... 1) | 1 |
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 replace src
by steps
and specs
:
- 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')
+ .steps('steps/**/*.js')
+ .specs('specs/**/*.feature')
.browsers([remoteConnection, 'chrome'])
.run();
};
You can use all other runner methods, that you like as well (e.g. filter
, screenshots
and reporter
).
Just like src
, you can add multiple paths to search for specs
and steps
:
runner
.step('location-1/*.js')
.step('location-2/*.js');
// or
runner.step(['location-1/*.js', 'location-2/*.js'])
To write step definitions, import Given
, When
and/ or Then
from cucumber
2:
const { Given, When, Then } = require('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, param1) => {
// Captured parameters in the step regex will be passed as arguments to the test implementation.
// "When Something great happens" will call this function with "great" as `param1`.
});
Then(/an assertion takes place/, async (t) => {
// Test code is the same as TestCafé's test function accepts.
await t.expect(true).ok();
});
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.
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. - Scenario outlines (Gherkin
scenario outline
andexamples
keywords): Will transform every example into on TestCafé test. - Tags/ Hooks: See Hooks.
In contrast to Cucumber.js' hooks, they are implemented differently in this package. Because of this inconsistency, this feature will change in the future to match the cucumber documentation better. 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.
This package only supports tagged hooks with a single tag as parameter. Each hook implementation gets TestCafé's test controller object as a parameter.
const { Before } = require('cucumber');
Before('@tag1', async (t) => {
// do something
});
In the future, untagged hooks will be supported.
The implementation of these hooks is seriously broken and should not be used.
Currently, BeforeAll
and AfterAll
hooks will be run before (or after) each test regardless of scenario tags.
In the future, they will be run before/ after a fixture. This will be a breaking change.