woocommerce/tests/e2e/env/README.md

192 lines
4.8 KiB
Markdown

# End to End Testing Environment
A reusable and extendable E2E testing environment for WooCommerce extensions.
## Installation
```bash
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.
```js
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.
```js
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.
```js
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.
```js
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).
```yaml
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.
```yaml
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
```bash
npm explore @woocommerce/e2e-environment -- npm run docker:up
```
Run E2E Tests
```bash
npm explore @woocommerce/e2e-environment -- npm run test:e2e
npm explore @woocommerce/e2e-environment -- npm run test:e2e-dev
```
Stop Docker
```bash
npm explore @woocommerce/e2e-environment -- npm run docker:down
```
## Additional information
Refer to [`tests/e2e/specs`](https://github.com/woocommerce/woocommerce/tree/master/tests/e2e/specs) for some test examples, and [`tests/e2e`](https://github.com/woocommerce/woocommerce/tree/master/tests/e2e) for general information on e2e tests.