wp-parsely / docs / TESTING.md

TESTING.md in Parse.ly 3.23.4, at docs/TESTING.md

136 lines 5.2 KB

Raw Download Zip

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/php@7.4/7.4.33_1/include/php/ext/pcre/pcre2.h
82
83	# If the /opt/homebrew/Cellar/php@7.4/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	- Finish:
115	- When you're finished testing, the WordPress environment can be stopped using `npm run dev:stop`.
116
117	### Automated E2E testing
118
119	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.
120
121	## Manual smoke test
122
123	Before releasing a new wp-parsely version, we should perform a basic manual smoke test which includes the following actions:
124
125	- Disable and re-enable the plugin
126	- Visit the settings page and click on the tabs
127	- Update a setting using the settings page
128	- Try to save an invalid Site ID and API Secret combination
129	- Try the Content Intelligence Widget and Sidebar with:
130	- An empty API Secret
131	- No Site ID
132	- Check that The Content Intelligence Post List Stats appears
133	- Check that "ld+json" and "parsely-cfg" are injected into the front-end
134
135	This list is currently a work in progress.
136