diff --git a/tests/e2e/env/README.md b/tests/e2e/env/README.md index f7030d045b4..ab96839f580 100644 --- a/tests/e2e/env/README.md +++ b/tests/e2e/env/README.md @@ -11,7 +11,7 @@ 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. +The `@woocommerce/e2e-environment` package exports configuration objects that can be consumed in JavaScript config files in your project. Additionally, it includes a hosting container for running tests and includes instructions for creating your Travis CI setup. ### Babel Config @@ -84,11 +84,11 @@ module.exports = { }; ``` -**NOTE:** Your project's Jest config file is expected to found at: `tests/e2e/config/jest.config.js`. +**NOTE:** Your project's Jest config file is expected to be 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. +The E2E environment provides a `@woocommerce/e2e-utils` alias for easy use of the WooCommerce E2E test helpers. ```js const { webpackAlias: coreE2EAlias } = require( '@woocommerce/e2e-environment' ); @@ -104,87 +104,12 @@ module.exports = { }; ``` -### Docker Setup +### Container 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). +Depending on the project and testing scenario, the built in testing environment container might not be the best solution for testing. This could be local testing where there is already a testing container, a repository that isn't a plugin or theme and there are multiple folders mapped into the container, or similar. The `e2e-environment` container supports using either the built in container or an external container. See the the appropriate readme for details: -```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 -``` +- [Built In Container](./builtin.md) +- [External Container](./external.md) ## Additional information diff --git a/tests/e2e/env/builtin.md b/tests/e2e/env/builtin.md new file mode 100644 index 00000000000..cd27ceea99b --- /dev/null +++ b/tests/e2e/env/builtin.md @@ -0,0 +1,104 @@ +# Using the Built In Container for End to End Testing + +This document provides general instructions for using `@woocommerce/e2e-environment` with the built in hosting container. + +## Prerequisites + +Complete the [setup instructions](./README.md) in each project/repository. + +## Initialization Requirements + +The test sequencer uses a `ready` page to determine that the testing environment is ready for testing. This page is created by the built in initialization. It matches the following spec: + +``` +wp post create --post_type=page --post_status=publish --post_title='Ready' --post_content='E2E-tests.' +``` + +### Project Initialization + +Each project will have its own begin test state and initialization script. For example, a project might start testing expecting that the [sample products](https://github.com/woocommerce/woocommerce/tree/master/sample-data) have already been imported. Below is the WP CLI equivalent of the built in initialization script for WooCommerce Core E2E testing: + + +``` +wp core install --url=http://localhost:8084 --admin_user=admin --admin_password=password --admin_email=wooadmin@example.org +``` + +Project specific initialization can be added through an executable file at ```tests/e2e/docker/initialize.sh```. WooCommerce core's script is: + + +``` +#!/bin/bash + +echo "Initializing WooCommerce E2E" + +wp plugin activate woocommerce +wp theme install twentynineteen --activate +``` + +### Container Configuration + +The built in container initialization needs to know the particulars of your test install to run the tests. The built in uses the following default settings: + + +``` +{ + "url": "http://localhost:8084/", + "users": { + "admin": { + "username": "admin", + "password": "password", + "email": "admin@woocommercecoree2etestsuite.com" + }, + "customer": { + "username": "customer", + "password": "password", + "email": "customer@woocommercecoree2etestsuite.com" + } + } +} +``` + +You can override these in `/tests/e2e/config/default.json`. The `customer` entry is not required by the sequencer but is required for the core test suite. + +### Folder Mapping + +The built in container defaults to mapping the root folder of the repository to a folder in the `plugins` folder. For example `woocommerce` is mapped to `/var/www/html/wp-content/plugins/woocommerce`. Use the `WC_E2E_FOLDER_MAPPING` environment variable to override this mapping. + +- Storefront Theme - ```WC_E2E_FOLDER_MAPPING=/var/www/html/wp-content/themes/storefront npm explore @woocommerce/e2e-environment -- npm run docker:up``` +- Site Project - ```WC_E2E_FOLDER_MAPPING=/var/www/html/wp-content/plugins npm explore @woocommerce/e2e-environment -- npm run docker:up``` + +### Travis CI Supported Versions + +Travis CI uses environment variables to allow control of some software versions in the testing environment. The built in container supports these variables: + +- `WP_VERSION` - WordPress (default `latest`) +- `TRAVIS_PHP_VERSION` - PHP (default `latest`) +- `TRAVIS_MARIADB_VERSION` - MariaDB (default `latest`) + +### Travis CI + +To enable Travis CI testing in your repository 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 docker:up + - 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 Travis related bash scripts to test whether it is an E2E test run. + diff --git a/tests/e2e/env/external.md b/tests/e2e/env/external.md new file mode 100644 index 00000000000..3ea7ff38910 --- /dev/null +++ b/tests/e2e/env/external.md @@ -0,0 +1,76 @@ +# Using an External Container for End to End Testing + +This document provides general instructions for using `@woocommerce/e2e-environment` with your hosting container. + +## Prerequisites + +Complete the [setup instructions](./README.md) in each project/repository. + +## Initialization Requirements + +The test sequencer uses a `ready` page to determine that the testing environment is ready for testing. It will wait up to 5 minutes for this page to be created. In your initialization script use + +``` +wp post create --post_type=page --post_status=publish --post_title='Ready' --post_content='E2E-tests.' +``` + +### Project Initialization + +Each project will have its own begin test state and initialization script. For example, a project might start testing expecting that the [sample products](https://github.com/woocommerce/woocommerce/tree/master/sample-data) have already been imported. Below is the WP CLI equivalent initialization script for WooCommerce Core E2E testing: + + +``` +wp core install --url=http://localhost:8084 --admin_user=admin --admin_password=password --admin_email=wooadmin@example.org +wp plugin activate woocommerce +wp theme install twentynineteen --activate +wp user create customer customer@woocommercecoree2etestsuite.com --user_pass=password --role=customer +``` + +### Test Sequencer Setup + +The test sequencer needs to know the particulars of your test install to run the tests. The sequencer reads these settings from `/tests/e2e/config/default.json`. The `customer` entry is not required by the sequencer but is required for the core test suite: + + +``` +{ + "url": "http://localhost:8084/", + "users": { + "admin": { + "username": "admin", + "password": "password" + }, + "customer": { + "username": "customer", + "password": "password" + } + } +} +``` + +### 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 +# add your initialization script here + - npm explore @woocommerce/e2e-environment -- npm run test:e2e + +.... + +after_script: +# add script to shut down your test container +``` + +Use `[[ ${RUN_E2E} == 1 ]]` in your Travis related bash scripts to test whether it is an E2E test run. +