woocommerce/tests/e2e/env/README.md

# End to End Testing Environment

A reusable and extendable E2E testing environment for WooCommerce extensions.

## Installation

```bash
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.

```js
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.

```js
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.

```js
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/config/jest.config.js`.

### Webpack Config

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

```js
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).

```yaml
version: '3.7'

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

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](https://docs.travis-ci.com/user/build-config-imports/) using `version: ~> 1.0` in your config file.

```yaml
version: ~> 1.0

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

....
```

## Usage

Start Docker

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

Run E2E Tests

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

Stop Docker

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