| 1 |
# Testing |
| 2 |
|
| 3 |
Besides the commands in this document, additional testing commands can be found within [](../composer.jsoncomposer.json](../composer.json](../composer.json) under the `scripts` and `scripts-descriptions` sections. |
| 4 |
|
| 5 |
## PHP unit tests |
| 6 |
|
| 7 |
``` |
| 8 |
# Run all single-site unit tests. |
| 9 |
composer test |
| 10 |
|
| 11 |
# Run all multisite unit tests. |
| 12 |
composer test-ms |
| 13 |
``` |
| 14 |
|
| 15 |
## PHP integration tests |
| 16 |
|
| 17 |
### Installing requirements |
| 18 |
|
| 19 |
In order to run integration tests, an installation script must be executed beforehand. For this to succeed, you will need to: |
| 20 |
|
| 21 |
- Have the `svn` command installed into your system. If you don't have it, you can install subversion to get it (`brew install subversion` if you're using brew). |
| 22 |
- Create a new dedicated test database in your local MySQL installation. Here we will assume that the database is named `wp_tests` with a username of `root` and an empty (`""`) password. |
| 23 |
- If you're on Windows, please also refer to [](WINDOWS.mdWINDOWS.md](WINDOWS.md](WINDOWS.md). |
| 24 |
|
| 25 |
To run the installation script: |
| 26 |
|
| 27 |
1. Navigate to the main plugin directory. |
| 28 |
2. Run the script: |
| 29 |
|
| 30 |
``` |
| 31 |
./bin/install-wp-tests.sh wp_tests root "" localhost latest true |
| 32 |
``` |
| 33 |
|
| 34 |
If you are using different credentials/settings, the structure of the command is as follows: |
| 35 |
|
| 36 |
``` |
| 37 |
./bin/install-wp-tests.sh <db-name> <db-user> <db-pass> [db-host] [wp-version] [skip-database-creation]" |
| 38 |
``` |
| 39 |
|
| 40 |
**Important Notes:** |
| 41 |
- It is recommended to always use `latest` as the value for the `wp-version` argument. |
| 42 |
- The installation takes place into a temporary directory, which means that the related files will get deleted between reboots. The way to remediate this is just to re-run the installation script whenever needed. |
| 43 |
- The database will be completely overwritten every time integration tests are executed. |
| 44 |
|
| 45 |
### Running integration tests |
| 46 |
|
| 47 |
``` |
| 48 |
# Run all single-site integration tests. |
| 49 |
composer testwp |
| 50 |
|
| 51 |
# You can use double dashes to add PHPUnit parameters. |
| 52 |
composer testwp -- --filter SettingsPageTest |
| 53 |
# The above will only run the SettingsPage test. |
| 54 |
|
| 55 |
# Run all multisite integration tests. |
| 56 |
composer testwp-ms |
| 57 |
|
| 58 |
# Run with coverage. |
| 59 |
composer coveragewp |
| 60 |
composer coveragewp -- --filter SettingsPageTest |
| 61 |
``` |
| 62 |
|
| 63 |
### Troubleshooting |
| 64 |
- If you encounter any `require` (class not found) issues, you can usually fix them by running `composer dump-autoload`. |
| 65 |
- If you're getting an error like `ERROR: The WordPress native unit test bootstrap file could not be found. Please set either the WP_TESTS_DIR or the WP_DEVELOP_DIR environment variable, either in your OS or in a custom phpunit.xml file.`, then most probably you need to re-run the integration tests installation script, as the related files get regularly deleted. |
| 66 |
|
| 67 |
## PHP code coverage |
| 68 |
|
| 69 |
### Installing requirements |
| 70 |
|
| 71 |
To be able to run coverage commands, you'll need to install `pcov`: |
| 72 |
|
| 73 |
``` |
| 74 |
pecl install pcov |
| 75 |
``` |
| 76 |
|
| 77 |
Some times, `pcov` does not work out of the box if `PHP` has been installed using Homebrew. Here are some possible troubleshooting steps (version strings should be updated to the ones you're using). |
| 78 |
|
| 79 |
``` |
| 80 |
# If missing, create a symlink to pcre2.h. |
| 81 |
ln -s /opt/homebrew/Cellar/pcre2/10.42/include/pcre2.h /opt/homebrew/Cellar/[email protected]/7.4.33_1/include/php/ext/pcre/pcre2.h |
| 82 |
|
| 83 |
# If the /opt/homebrew/Cellar/[email protected]/7.4.33_1/pecl symlink points to a |
| 84 |
# directory that does not exist, create the directory. |
| 85 |
mkdir /opt/homebrew/lib/php/pecl |
| 86 |
``` |
| 87 |
|
| 88 |
### Running code coverage |
| 89 |
|
| 90 |
``` |
| 91 |
composer coverage |
| 92 |
``` |
| 93 |
|
| 94 |
## JavaScript tests |
| 95 |
|
| 96 |
``` |
| 97 |
# Run front-end tests. |
| 98 |
npm run test |
| 99 |
``` |
| 100 |
|
| 101 |
## End-to-end (E2E) tests |
| 102 |
|
| 103 |
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. |
| 104 |
|
| 105 |
### How to run E2E tests |
| 106 |
|
| 107 |
- Make sure that [](CONTRIBUTING.md#minimum-requirementsrequirements](CONTRIBUTING.md#minimum-requirements](CONTRIBUTING.md#minimum-requirements) are installed and that you have the dependencies up to date by running `npm install`. |
| 108 |
- Start the WordPress environment: |
| 109 |
- From the `wp-parsely` directory, run `npm run dev:start`. Once you see a line that says `✔ Done! (in XXXs YYYms)`, you may proceed. |
| 110 |
- Run the tests: |
| 111 |
- To run all E2E tests: `npm run test:e2e`. |
| 112 |
- To run a specific test: `npm run test:e2e activation-flow.spec.js`. |
| 113 |
- For debugging purposes, you might want to run tests visually: `npm run test:e2e:debug`. |
| 114 |
- By default, the tests run against the wp-env tests site, on the port set by `WP_ENV_TESTS_PORT` or `.wp-env.override.json` (8889 otherwise). To target another site, set `WP_BASE_URL`, for example `WP_BASE_URL=http://localhost:8080 npm run test:e2e`. |
| 115 |
- Finish: |
| 116 |
- When you're finished testing, the WordPress environment can be stopped using `npm run dev:stop`. |
| 117 |
|
| 118 |
### Automated E2E testing |
| 119 |
|
| 120 |
Our E2E tests are hooked into a [](../.github/workflows/e2e-tests.ymlGitHub Workflow](../.github/workflows/e2e-tests.yml](../.github/workflows/e2e-tests.yml), so commits pushed to GitHub will be tested using our E2E tests. |
| 121 |
|
| 122 |
## Manual smoke test |
| 123 |
|
| 124 |
Before releasing a new wp-parsely version, we should perform a basic manual smoke test which includes the following actions: |
| 125 |
|
| 126 |
- Disable and re-enable the plugin |
| 127 |
- Visit the settings page and click on the tabs |
| 128 |
- Update a setting using the settings page |
| 129 |
- Try to save an invalid Site ID and API Secret combination |
| 130 |
- Try the Content Intelligence Widget and Sidebar with: |
| 131 |
- An empty API Secret |
| 132 |
- No Site ID |
| 133 |
- Check that The Content Intelligence Post List Stats appears |
| 134 |
- Check that "ld+json" and "parsely-cfg" are injected into the front-end |
| 135 |
|
| 136 |
This list is currently a work in progress. |
| 137 |
|
