woocommerce/tests/e2e-env

End to End Testing Environment

A reusable and extendable E2E testing environment for WooCommerce extensions.

Installation

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

Configuration

The @woocommerce/e2e-env 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

Extend your project's Babel config to contain the expected presets for E2E testing.

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

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-env' );

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-env' );

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-tests/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-env' );

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-tests/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

The E2E environment includes a base .travis.yml file that sets up a WordPress testing environment and defines a job for running E2E tests. Opt in to Travis Build Config Imports using version: ~> 1.0 in your config file.

version: ~> 1.0

import:
  - source: node_modules/@woocommerce/e2e-env/.travis.yml
    mode: deep_merge_prepend # Merge the package config first.

....

Usage

Start Docker

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

Run E2E Tests

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

Stop Docker

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