WebdriverIO Autotest Framework

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.

Features

• Simple setup, no need for local preinstalled Selenium Grid and browser drivers
• Test with Chrome and Firefox with zero configuration
• Integrated with WebdriverIO v6
• Page Object Pattern example, BDD tests with Cucumber and over 150 predefined steps
• Implement custom steps with TypeScript
• Support for debugging tests
• Detailed report generation (Allure Report Example)
• Integration with CI tools (CircleCI, Azure DevOps)

Requirements

• 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

Quick start

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
npm run test

# open the report
npm run report

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.

Test examples

File
./src/features/google.search.feature	An example of testing the Google search using Page Object pattern
./src/features/sample.snippets.feature	Samples of using the existing test snippets. Credits Christian Bromann

Adding 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 unknown term
        When I set "google" to the search field
            And  I press "Enter"
        Then I expect that search element 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.

Implementing custom steps

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.

Browser specific tests

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

Pending tests

To skip a test, use the @Pending tag:

Feature: Performing a Google Search

    ...

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

Verbose tests

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

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.

Configurations

Environment variables

The configurable options are set in the .env file.

Variable	Usage
SELENIUM_VERSION	Configure the version of selenium hub and nodes. Change this version if you want to run tests against a specific browser version. See the list of available selenium releases and browser versions.
SCREEN_WIDTH SCREEN_HEIGHT	Configure browser window size.

WebdriverIO options

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',
  ...

Debugging tests

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:

• 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.

Running tests

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:run:local:chrome
or
npm run test:run:local:firefox

License

MIT