woocommerce/tests/e2e-tests/README.md

# WooCommerce End to End Tests

Automated end-to-end tests for WooCommerce.

## Table of contents

- [Pre-requisites](#pre-requisites)
  - [Install NodeJS](#install-nodejs)
  - [Install dependencies](#install-dependencies)
  - [Configuration](#configuration)
      - [Test Configuration](#test-configuration)
      - [Environment Variables](#environment-variables)
- [Running tests](#running-tests)
  - [How to run tests](#how-to-run-tests) 
- [Writing tests](#writing-tests) 
- [Debugging tests](#debugging-tests)

## Pre-requisites

### Install NodeJS

```bash
brew install node #MacOS
```

### Install dependencies

```bash
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`](https://github.com/WordPress/gutenberg/tree/master/packages/e2e-test-utils) package is being used. The function relies on the following [`config.js`](https://github.com/WordPress/gutenberg/blob/master/packages/e2e-test-utils/src/shared/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:

```bash
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:
                                    
```bash
"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:

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

```bash
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](https://github.com/GoogleChrome/puppeteer) – a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol
- [jest-puppeteer](https://github.com/smooth-code/jest-puppeteer) – provides all required configuration to run tests using Puppeteer
- [expect-puppeteer](https://github.com/smooth-code/jest-puppeteer/tree/master/packages/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](https://github.com/WordPress/gutenberg/tree/master/packages/e2e-test-utils).

## 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](https://developers.google.com/web/tools/puppeteer/debugging).