Boilerplate project to write BDD tests with Cucumber and execute with docker selenium. Tests are written in an ordinary language that bridges the gap between business and technical people. The docker selenium simplifies the setup and avoids any local installation of browser specific dependencies.

• Simple setup, no need for local preinstalled Selenium Grid and browser drivers
• Test with Chrome and Firefox with zero configuration
• Integrated with WebdriverIO
• BDD tests with Cucumber and over 150 predefined steps
• Implement custom steps with TypeScript
• Support for debugging tests
• Possibility to visually see the execution in browser with VNC
• Detailed report generation (example)
• Integration with CI tools

• To run Firefox and Chrome browsers with docker selenium you need:

  • docker
  • docker-compose

• Tests are executed with Node.js, requires:

  • Node.js version 10 or higher
  • npm version 6 or higher

1. Install dependencies required to run the tests:

npm install

2. Start docker selenium containers with docker-compose:

# starts the selenium hub and browser nodes in docker containers
npm run selenium

3. Run the tests and view the report:

# run tests and open the report
npm run test

To stop all the docker containers from step 2:

npm run selenium:stop

Note that selenium containers can be started once and then used across multiple sessions of running and debugging tests.

Tests are written using Gherkin syntax in a fashion that can be used as feature documentation:

# This is a single line comment
Feature: Performing a Google Search

    As a user on the Google search page
    I want to search for Selenium-Webdriver
    Because I want to learn more about it

    Background:
        Given I open the url "https://google.com"

    Scenario: Searching for Selenium Webdriver
        When I set "Selenium Webdriver" to the inputfield "[name=q]"
        And  I press "Enter"
        Then I expect that element "#search" becomes displayed

All tests should be located in ./src/features/* directory with extension .feature (configured in ./config/tests.config.ts).
For a list of predefined and supported steps see files:

• ./src/steps/given.ts
• ./src/steps/when.ts
• ./src/steps/then.ts.

The steps are inspired from cucumber-boilerplate repository.

There are over 150 predefined steps, but in case you need an extra step you can add it in one of the ./src/steps file.
The snippets are defined using regular expressions. It allows to implement powerful and complex sentences. Everything that's within "([^"]*)?" gets captured and appended to the callback.
To access browser functionality, reference the global variable browser which is a WebdriverIO browser instance. See the documentation for a list of supported methods.
Assertions are written using chai.

To run a test against a specific browser use predefined tags:

Feature: Performing a Google Search

    ...

    # This scenario will run only in Chrome browser
    @OnlyChrome
    Scenario: Searching in chrome browser
    ...

    # This scenario will run only in Firefox browser
    @OnlyFirefox
    Scenario: Searching in Firefox browser
    ...

To skip a test, use the @Pending tag:

Feature: Performing a Google Search

    ...

    # This scenario will be skipped
    @Pending
    Scenario: Searching for WebdriverIO
    ...

Currently, a screenshot is attached only for a failing test. In case you want screenshots for a test regardless of its completion status, use the @Verbose tag:

Feature: Performing a Google Search

    ...

    # A screenshot and additional test details will be attached to the report
    @Verbose
    Scenario: Searching for WebdriverIO
    ...

Hooks are blocks of code that can run at various points in the Cucumber execution cycle. It is possible to write conditional hooks.
See examples of scenario hooks in ./src/steps/hooks.ts. For a more advanced usage, configure hooks in ./config/hooks.config.ts.

You can customize existing hooks or implement your own. See the WebdriverIO documentation about hooks.

The configurable options are set in the .env file.

WebdriverIO specific options are all in ./config directory.
For example, to configure a default url change the baseUrl option in ./config/index.ts:

export const config = {
  runner: 'local',
  baseUrl: 'https://webdriver.io',
  ...

There is a ./.vscode/launch.json file that has a debugger configuration for Visual Studio Code, but you can enable debugging in any other editor that supports integration with Node.js debugger.

To debug a single feature file:

• Prerequisites: selenium containers are running (npm run selenium)

• The .feature file to test is active in VS Code

• From VS Code Run and Debug menu select the Debug current test option

The test will start and run only the current file. Once started you can navigate to any .ts file and place a breakpoint.

To debug all files follow the same steps but use the Debug all tests option.

In some cases, you might need to visually see the execution in the browser. That is possible thanks to docker selenium debug images that have XVFB and VNC server installed. Note that debug images are slower and are intended only for development mode.

Download on your machine the VNC viewer.

If you already have docker selenium containers running, stop them:

npm run selenium:stop

Start selenium debug containers that enable the VNC support:

# starts the selenium containers with VNC support
npm run selenium:vnc

Now you can connect and enter the remote session.

Tests by default run in headless mode so that a browser window is not visually created. To run the tests with enabled browser window:

# runs the tests without headless option
npm run test:vnc

Note that even if you started selenium with VNC support, you need to run the test:vnc command to see the browsers visually.

Debugging with VNC support is also possible. If you're using Visual Studio Code there are VNC Debug current test and VNC Debug all tests debugging configurations that work similar to configurations described in Debugging tests section.

To stop the debug containers use the same command:

npm run selenium:stop

Integration with a CI tool is easy if it supports docker and docker-compose tools.
There is a Dockerfile to build an image that bundles Node.js, npm and tests. The docker-compose.ci.yml configures all the dependencies required to run the tests in containers:

docker-compose -f docker-compose.ci.yml up --abort-on-container-exit --exit-code-from node

There are npm scripts to avoid running long commands:

# only builds the Dockerfile image
npm run ci:build

# runs the tests in containers
npm run ci

CI	Status	Config	Artifacts
CircleCI		./.circleci/default.yml	Report uploaded as artifacts that can be viewed directly in the browser.
Github Actions		./.github/workflows/main.yml	Report files available as a downloadable zip in artifacts.
TravisCI		./.travis.yml	You need to configure Amazon S3 account to enable artifacts.

MIT