woocommerce/tests/e2e-tests/README.md

WooCommerce End to End Tests

Automated end-to-end tests for WooCommerce.

Table of contents

• Pre-requisites
  • Install NodeJS
  • Install dependencies
  • Configuration
    • Test Configuration
    • Environment Variables
• Running tests
  • How to run tests
• Writing tests
• Debugging tests

Pre-requisites

Install NodeJS

brew install node #MacOS

Install dependencies

npm install

Configuration

Test Configuration

The tests use environment variables to specify login test data needed to run tests.

To login to the site, loginUser() utility function of e2e-test-utils package is being used. The function relies on the following config.js file to specify base URL (site where the tests will be running), Admin user details and Customer user details:

const WP_ADMIN_USER = {
 	username: 'admin',
 	password: 'password',
 };
 
 const {
 	WP_USERNAME = WP_ADMIN_USER.username,
 	WP_PASSWORD = WP_ADMIN_USER.password,
 	WP_BASE_URL = 'http://localhost:8889',
 } = process.env;
 
 export {
 	WP_ADMIN_USER,
 	WP_USERNAME,
 	WP_PASSWORD,
 	WP_BASE_URL,
 };

As per above, create an Admin user (with Administrator role) on the site and set its username and password exactly as shown below:

• username: admin
• password: password

Next, create a Customer user (with Customer role) on the site. Feel free to give it any username and password.

Note that wp-admin tests are being run as an Admin user and front-end tests are being run as a Customer user.

Finally, specify base URL and Customer user details using environment variables.

Environment variables

Set environmental variables (base URL and Customer user) as shown below. Note that you don't need to add the trailing slash ('/') at the end of the site URL:

• export WP_BASE_URL={your site URL}
• export WP_USERNAME={your Customer user username}
• export WP_PASSWORD={your Customer user password}

You can unset the variables when you are done:

• unset WP_BASE_URL
• unset WP_USERNAME
• unset WP_PASSWORD

Running tests

How to run tests

To run e2e tests use the following command:

npm run test:e2e

Tests are being run headless by default. However, sometimes it's useful to observe the browser while running tests. To do so, Development mode can be enabled by passing --dev flag to the test:e2e script in ./package.json file as follows:

"test:e2e": "./tests/bin/e2e-test-integration.js --dev",

Once done, start tests as usual by running npm run test:e2e.

The Development mode also enables SlowMo mode. SlowMo slows down Puppeteer’s operations so we can better see what is happening in the browser. You can adjust the SlowMo value by editing PUPPETEER_SLOWMO variable in ./tests/e2e-tests/config/jest-puppeteer.dev.config.js file. The default PUPPETEER_SLOWMO=50 means test actions will be slowed down by 50 milliseconds.

To run an individual test, use the direct path to the spec. For example:

npm run test:e2e ./tests/e2e-tests/specs/wp-admin/wp-admin-product-new.test.js

You can also provide the base URL, Test username and Test password like this:

WP_BASE_URL={your site URL} WP_USERNAME={your Test user username} WP_PASSWORD={your Test user password} npm run test:e2e

Writing tests

We use the following tools to write e2e tests:

• Puppeteer – a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol
• jest-puppeteer – provides all required configuration to run tests using Puppeteer
• expect-puppeteer – assertion library for Puppeteer

Tests are kept in tests/e2e-tests/specs folder.

The following packages are being used to write tests:

• e2e-test-utils - End-To-End (E2E) test utils for WordPress. You can find the full list of utils here.

Debugging tests

Debugging tools are pre-built in the existing Puppeteer's architecture. To enable debugging:

• Run tests in the Development mode;
• Use await jestPuppeteer.debug(); in test code to pause execution.

Doing the above will allow for the following:

• Tests to be run non-headless;
• SlowMo mode enabled;
• Chrome Dev Tools open by default;
• Test timeout time increased to 2 minutes.

If more than 2 minutes needed for inspection, adjust the jestTimeoutInMilliSeconds value in ./tests/e2e-tests/config/jest.setup.js.

For more Puppeteer debugging tips, check Google's documentation.