cypress-scenario-runner v2.0.0-beta.0

Cypress Scenario Runner

Write runnable Gherkin scenarios without a single line of test code. Powered by Cypress.

Step 1: Write your Gherkin scenario

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"

Step 2: Add matching data-test attributes to your HTML

<!-- 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>

Step 3: That's it. There's no step 3!

cypress-scenario-runner will run the scenario as-is, no given/when/then glue code needed.

Table of contents

• Installation
• Configuration
• Usage
• Examples
• Customization
• Contributing

Installation

Requires Node.js v8+

1. Install packages

Install this package 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 it once to create the initial directory structure.

3. Set up cypress-scenario-runner

Add these lines to the pluginsFile listed in your cypress.json (default path is cypress/plugins/index.js):

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

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

Add these lines to the supportFile listed in your cypress.json (default path is cypress/support/index.js):

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

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

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

Now you're ready to begin writing test scenarios.

Usage

Writing Gherkin scenarios

A Gherkin scenario 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 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

Once you've written your scenarios, annoated associated elements, and added any necessary routes, running these scenarios is simple. Launch Cypress using your preferred method (eg. $(npm bin)/cypress open) and select the scenarios you want to run.

Examples

See the cypress/integration/ directory for examples.

Customization

Coming soon.