browser-tests.md

Browser tests

Ginger ships with an automated end-to-end browser testing setup, batteries included. The tests are written in Gherkin, executed by Nightwatch.js and run against a Selenium-based headless Chrome instance.

The setup consists of:

• a selenium Docker container with a headless Chrome, so you can run the tests in a CI environment as well
• a node-tests container that contains Nightwatch.js and its WebDriver client and executes the JavaScript
• a Nightwatch.js configuration
• Cucumber.js step definitions geared towards Ginger sites.

Writing browser site tests

In your Ginger site, add a features/ directory. In this directory, add .feature files to describe your site’s behaviour. For instance:

# yoursite/features/homepage.feature
Feature: homepage

Scenario: homepage title

    When I visit "/"
    Then the title is "Welcome to my website!"

For more information, consult Ginger’s step definitions and the Cucumber.js docs.

Running your tests

Run in Docker

To run your tests:

$ make test site=yoursite

When a test fails, a screenshot is automatically made and stored in tests/screenshots.

Run locally

To run the tests on your local Chrome instance, so you can see what is happening:

$ make test-chrome site=yoursite

Pass arguments to Nightwatch

For instance, to execute only tests tagged @wip:

$ make test site=yoursite args=--tag=wip

Run tests against a remote URL

To test a remote URL:

$ make test site=yoursite url=http://yoursite.com

IDE integration

• In IntelliJ IDE, including WebStorm, install the Cucumber.js plugin. WebStorm comes bundled with Gherkin support; in IntelliJ you can install the Gherkin plugin.

Troubleshooting

Tests fail with driver error

Try to reset the Selenium Docker container:

$ docker-compose stop selenium
$ make test site=yoursite