| @@ -97,23 +97,39 @@ | ||
| 97 | 97 | ## End-to-end (E2E) tests |
| 98 | 98 | |
| 99 | 99 | This suite is meant to simulate actual user actions as they interact with the plugin. Tests are run against a real WordPress instance and activities are performed in a real browser. The idea is that we can provide confidence that changes going forward have the intended effect on the DOM and rendered content that plugin users and site visitors will see under various specific conditions. |
| 100 | 100 | |
| 101 | +### How E2E tests work | |
| 102 | + | |
| 103 | +In order for the tests to do their job, they need a WordPress instance. To that end, we spin up a bare-bones containerized site and configure it to the default values for the WordPress `e2e-tests` helper. We then leverage the `@wordpress/scripts` utility's [built-in functionality](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#test-e2e) to launch a browser via [Puppeteer](https://pptr.dev/). | |
| 104 | + | |
| 105 | +The tests use the [Jest framework](https://jestjs.io/) to drive a user flow and assert on expected outcomes. In addition to the [Puppeteer API](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md), there are a number of helpers to accomplish frequently performed tasks in the [`@wordpress/e2e-test-utils` package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-e2e-test-utils/). | |
| 106 | + | |
| 107 | +See this post for more information: https://make.wordpress.org/core/2019/06/27/introducing-the-wordpress-e2e-tests/ | |
| 108 | + | |
| 101 | 109 | ### How to run E2E tests |
| 102 | 110 | |
| 103 | 111 | - Make sure that [requirements](CONTRIBUTING.md#minimum-requirements) are installed and that you have the dependencies up to date by running `npm install`. |
| 104 | -- Start the WordPress environment: | |
| 112 | + | |
| 113 | +- Start the back-end: | |
| 114 | + | |
| 105 | 115 | - From the `wp-parsely` directory, run `npm run dev:start`. Once you see a line that says `✔ Done! (in XXXs YYYms)`, you may proceed. |
| 116 | + | |
| 106 | 117 | - Run the tests: |
| 107 | - - To run all E2E tests: `npm run test:e2e`. | |
| 108 | - - To run a specific test: `npm run test:e2e activation-flow.spec.js`. | |
| 109 | - - For debugging purposes, you might want to run tests visually: `npm run test:e2e:debug`. | |
| 118 | + | |
| 119 | + - Once your environment is ready, you can launch the e2e tests suite by running `npm run test:e2e`. This will run the test suite using a headless browser. | |
| 120 | + | |
| 121 | + - For debugging purpose, you might want to follow the test visually. You can do so by running the tests in an interactive mode: `npm run test:e2e:interactive` | |
| 122 | + | |
| 123 | + - You can also run a given test file separately: `npm run test:e2e tests/e2e/specs/activation-flow.spec.js` | |
| 124 | + | |
| 110 | 125 | - Finish: |
| 111 | - - When you're finished testing, the WordPress environment can be stopped using `npm run dev:stop`. | |
| 112 | 126 | |
| 127 | + - When you're finished testing, the back-end containers and storage can be stopped using `npm run dev:stop`. | |
| 128 | + | |
| 113 | 129 | ### Automated E2E testing |
| 114 | 130 | |
| 115 | -Our E2E tests are hooked into a [GitHub Workflow](../.github/workflows/e2e-tests.yml), so commits pushed to GitHub will be tested using our E2E tests. | |
| 131 | +Our E2E tests are hooked into a GitHub workflow called [End-to-end (e2e) Tests](../.github/workflows/e2e-tests.yml), which uses the same environment mentioned above to spin-up a WordPress environment. Commits pushed to GitHub will be tested against that environment using our E2E tests. | |
| 116 | 132 | |
| 117 | 133 | ## Manual smoke test |
| 118 | 134 | |
| 119 | 135 | Before releasing a new wp-parsely version, we should perform a basic manual smoke test which includes the following actions: |
