cypress-scenario-runner v2.1.0-beta.4

Cypress Scenario Runner

Run Gherkin scenarios with Cypress without a single line of code.

By adding a few HTML attributes:

<input … data-test="email input" />
<input … data-test="password input" />
<button … data-test="login button">Login</button>

Cypress Scenario Runner can run Gherkin scenarios without any Cypress code like cy.visit(), cy.click():

Feature: Login
===

Scenario: Successful login
---
Given I navigate to "login"
And I set "email input" to "name@example.com"
And I set "password input" to "abc123"
When I click "login button"
Then I should be on "home"

Table of contents

• Installation & setup
• Usage
• Customization
• Contributing

Installation

Cypress Scenario Runner requires Node.js v8.0+, cypress, and cypress-cucumber-preprocessor.

npm install --save-dev cypress cypress-cucumber-preprocessor cypress-scenario-runner

Configuration

TBD

Installation & setup

1. Install packages
2. Set up Cypress
3. Set up Cypress Scenario Runner

NOTE: Cypress Scenario Runner requires Node.js v8.0+

1. Install packages

Install cypress-scenario-runner and its dependencies, cypress and cypress-cucumber-preprocessor:

npm install --save-dev cypress cypress-cucumber-preprocessor cypress-scenario-runner

2. Set up Cypress

Follow the setup instructions for Cypress and launch its GUI at least once in order to create the initial Cypress directory structure.

3. Set up cypress-scenario-runner

Edit the Cypress plugins file:

const cucumber = require('cypress-cucumber-preprocessor').default

module.exports = (on, config) => {
	on('file:preprocessor', cucumber())
}

Edit the Cypress support file:

const { addCommands } = require('cypress-scenario-runner')
addCommands()

Create a new file at cypress/support/step_definitions/index.js:

const { addSteps } = require('cypress-scenario-runner')
addSteps()

Now you're ready to begin writing test scenarios.

Usage

• Writing test scenarios
• Annotating HTML elements
• Setting routes
• Running scenarios

Writing test scenarios

Test scenarios are written in Gherkin syntax which looks like this:

Feature: Login
===

Scenario: Successful login
---
Given I navigate to "login"
And I set "email input" to "name@example.com"
And I set "password input" to "abc123"
When I click "login button"
Then I should be on "home"

Each given/when/then/and line is called a "step". cypress-scenario-runner works by using a comprehensive set of reusable step templates that have already been implemented behind the scenes:

Parameters appear in {brackets} in step templates and in "double quotes" in the scenario. For example, this step:

And I set "email input" to "name@example.com"

corresponds to this step template:

I set {element} to {string}

where:

{element} = email input
{string}  = name@example.com

In addition, the full Gherkin specification is supported along with additional enhancements by cypress-cucumber-preprocessor. For instance, you can use scenario templates/outlines, data tables, and tags in your scenarios.

See the cypress/integration/ directory for more examples.

Annotating HTML elements

HTML attributes are used to map the {element} step parameters to their corresponding HTML elements. data-test is used by default, but this is configurable.

<!-- login.html -->
<input name="email" data-test="email input" />
<input name="password" data-test="password input" />
<button type="submit" data-test="login button">Login</button>

Setting routes

Routes need to provided for navigation steps like these to work:

Given I navigate to "login"

A map of all label => path routes should be provided to addSteps() in the cypress/support/step_definitions/index.js file created during installation. Route paths can be relative to the web root or absolute URLs.

const { addSteps } = require('cypress-scenario-runner')
addSteps({
+	routes: {
+		login: '/login',
+	},
})

Running scenarios

Scenario files can be run directly with Cypress:

$(npm bin)/cypress run [files]

or, using the Cypress UI:

$(npm bin)/cypress open

Customization

Coming soon.