Provisioning TestCafe

From Tokaido 1.10, we've included a way to easily get up and running with a limited set of TestCafe fixtures.


In previous versions, the `tok test` command was used to provision a framework for the built in Drupal Nightwatch tests. Based on feedback from Tokaido users, the decision has been made to shift the testing framework to TestCafe from 1.10 onwards.

Getting started is very simple with the command:

tok test

On the first run of this command, Tokaido will download a set of example tests for you to be able to extend upon, and also install the required Node.js dependencies.

You continue to run tok test in order to invoke tests at any time, so this command not only provisions the test environment first time, but also runs tests each and every time.

After you run tok test for the first time, the downloaded test config files can be found in .tok/testcafe

├── .tok
  ├── testcafe
    ├── package-lock.json
    ├── package.json
    └── tests
        ├── bootstrap.js
        ├── config.js
        ├── fixtures
        │   ├── content.js
        │   ├── login.js
        │   └── pages.js
        └── reports
            ├── screenshots
            └── videos

The .tok/testcafe directory should be committed back into your Git repository so that it can be shared with other people working on your project.

Tokaido never re-creates or modifies this directory, so you should feel free to make changes here once you've made that initial tok test run.

Debugging Tests

The Test website

As the test database is retained at the end of the test run, you'll be able to hit the test website to test and debug yourself as a user.

The URL for the test version of the website https://{PROJECT_NAME}

As opposed to the website hitting the 'default' database


Test Reporting

During the setup phase, Tokaido sets up screenshots, video and xunit reports.

These can be reviewed after your test run in .tok/testcafe/tests/reports

Extending Your Tests

When you've run tok test for the first time, you can find the set of example tests in .tok/testcafe/tests/fixtures. The standard TestCafe API can be used here to create new tests and fixtures.

Ironstar, the team who develops Tokaido, have also teamed up with the Drupal agency (Technocrat)[] to create a library for convenience when working with TestCafe and Drupal. (GitHub testcafe-drupal)[]

The TestCafe Drupal Package

To make it easier to use TestCafe with Drupal, we've created the testcafe-drupal NPM package. We would very much like to thank our friends at Technocrat who helped us with putting this together.

When you run tok test, this package is automatically downloaded and installed for you.

Configuring TestCafe

The testcafe/tests/boostrap.js file can be used for configuring the TestCafe runner, including:

  • Target browser
  • Reporting type and output directory
  • Video/screenshot configuration

More information about configuring the TestCafe runner can be found here

The testcafe/tests/config.js file is more relevant to Drupal and can be used to configure the testcafe-drupal library, including:

  • Drupal base URL (best not to change this if running tests through Tokaido)
  • User declaration
  • Selector definitions

More information about the drupal-testcafe config can be found here

Test Database

When running the tok test command, the bootstrap phase creates a clone of your existing Tokaido database and creates two new users, 'user' and 'administrator'. This can take around 40 seconds to complete. By default, all tests are run against this cloned database.

This method of testing against an isolated database creates more predictable tests. This is achieved by:

  • Changes made to the database in the tests won't affect the state of your development environment
  • A fresh copy each time you run tok test means that gradual state drift by running your test cases over time is diminished

Persisting the Test Database

At the end of a test suite run, the test database is left in place. Next time you run tok test, however, the test database is replaced with a fresh clone.

A bootstrap time of 40 seconds for each run is a little long, so we added a way to skip cloning with a flag.

tok test --use-existing-db

This flag should only be used if you're trying to quickly re-run a set of tests and not concerned about state.

Notice something wrong? Shoot us a PR!