woocommerce/tests/e2e/env

End to End Testing Environment

A reusable and extendable E2E testing environment for WooCommerce extensions.

Installation

npm install @woocommerce/e2e-environment --save
npm install jest --global

Configuration

The @woocommerce/e2e-environment package exports configuration objects that can be consumed in JavaScript config files in your project. Additionally, it contains several files to serve as the base for a Docker container and Travis CI setup.

Babel Config

Make sure you npm install @babel/preset-env --save if you have not already done so. Afterwards, extend your project's babel.config.js to contain the expected presets for E2E testing.

const { babelConfig: e2eBabelConfig } = require( '@woocommerce/e2e-environment' );

module.exports = function( api ) {
	api.cache( true );

	return {
		...e2eBabelConfig,
		presets: [
			...e2eBabelConfig.presets,
			'@wordpress/babel-preset-default',
		],
		....
	};
};

ES Lint Config

The E2E environment uses Puppeteer for headless browser testing, which uses certain globals variables. Avoid ES Lint errors by extending the config.

const { esLintConfig: baseConfig } = require( '@woocommerce/e2e-environment' );

module.exports = {
	...baseConfig,
	root: true,
	parser: 'babel-eslint',
	extends: [
		...baseConfig.extends,
		'wpcalypso/react',
		'plugin:jsx-a11y/recommended',
	],
	plugins: [
		...baseConfig.plugins,
		'jsx-a11y',
	],
	env: {
		...baseConfig.env,
		browser: true,
		node: true,
	},
	globals: {
		...baseConfig.globals,
		wp: true,
		wpApiSettings: true,
		wcSettings: true,
	},
	....
};

Jest Config

The E2E environment uses Jest as a test runner. Extending the base config is needed in order for Jest to run your project's test files.

const path = require( 'path' );
const { jestConfig: baseE2Econfig } = require( '@woocommerce/e2e-environment' );

module.exports = {
	...baseE2Econfig,
	// Specify the path of your project's E2E tests here.
	roots: [ path.resolve( __dirname, '../specs' ) ],
};

NOTE: Your project's Jest config file is expected to found at: tests/e2e/config/jest.config.js.

Webpack Config

The E2E environment provides a @woocommerce/e2e-tests alias for easy use of the WooCommerce E2E test helpers.

const { webpackAlias: coreE2EAlias } = require( '@woocommerce/e2e-environment' );

module.exports = {
	....
	resolve: {
		alias: {
			...coreE2EAlias,
			....
		},
	},
};

Docker Setup

The E2E environment will look for a docker-compose.yaml file in your project root. This will be combined with the base Docker config in the package. This is where you'll map your local project files into the Docker container(s).

version: '3.3'

services:

  wordpress-www:
    volumes:
      # This path is relative to the first config file
      # which is in node_modules/@woocommerce/e2e/env
      - "../../../:/var/www/html/wp-content/plugins/your-project-here"

  wordpress-cli:
    volumes:
      - "../../../:/var/www/html/wp-content/plugins/your-project-here"

Docker Container Initialization Script

You can provide an initialization script that will run in the WP-CLI Docker container. Place an executable file at tests/e2e/docker/initialize.sh in your project and it will be copied into the container and executed. While you can run any commands you wish, the intent here is to use WP-CLI to set up your testing environment. E.g.:

#!/bin/bash

echo "Initializing WooCommerce E2E"

wp plugin install woocommerce --activate
wp theme install twentynineteen --activate
wp user create customer customer@woocommercecoree2etestsuite.com --user_pass=password --role=customer --path=/var/www/html
wp post create --post_type=page --post_status=publish --post_title='Ready' --post_content='E2E-tests.'

Travis CI

Add the following to the appropriate sections of your .travis.yml config file.

version: ~> 1.0

  include:
    - name: "Core E2E Tests"
    php: 7.4
    env: WP_VERSION=latest WP_MULTISITE=0 RUN_E2E=1

....

script:
  - npm install jest --global
  - npm explore @woocommerce/e2e-environment -- npm run test:e2e

....

after_script:
  - npm explore @woocommerce/e2e-environment -- npm run docker:down

Use [[ ${RUN_E2E} == 1 ]] in your bash scripts to test for the core e2e test run.

Usage

Start Docker

npm explore @woocommerce/e2e-environment -- npm run docker:up

Run E2E Tests

npm explore @woocommerce/e2e-environment -- npm run test:e2e
npm explore @woocommerce/e2e-environment -- npm run test:e2e-dev

Stop Docker

npm explore @woocommerce/e2e-environment -- npm run docker:down

Additional information

Refer to tests/e2e/specs for some test examples, and tests/e2e for general information on e2e tests.