From 66d287944559a0108e12c6f2a78c4301929164cc Mon Sep 17 00:00:00 2001 From: Carsten Bach Date: Fri, 27 Sep 2024 23:37:20 +0200 Subject: [PATCH 1/3] NEW docs about unit tests --- docs/contributor/unit-tests/README.md | 89 +++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/contributor/unit-tests/README.md diff --git a/docs/contributor/unit-tests/README.md b/docs/contributor/unit-tests/README.md new file mode 100644 index 000000000..4edbfed87 --- /dev/null +++ b/docs/contributor/unit-tests/README.md @@ -0,0 +1,89 @@ +# PHP Unit tests + +GatherPress allows to run **automated & manual php unit tests**, while sharing the same, `wp-env` based, setup. + +## Automated tests + +Check the results of the [*phpunit-tests action workflow*](https://github.com/GatherPress/gatherpress/actions/workflows/phpunit-tests.yml) at `https://github.com/GatherPress/gatherpress/actions/workflows/phpunit-tests.yml`. + +## Manual tests + +The unittest-setup can also be used to manually run the test suite. In general, only a `wp-env` instance is needed. + +### Install dependencies + +To run the unit tests you will have to install the requirements using the following commands: + +```bash +composer install +``` + +> [!NOTE] +> You also need to use Node.js 20 or later + +Install the dependencies to create the Playground testing instance, using the following command: + +```bash +npm ci --legacy-peer-deps +``` + +### Start the Environment + +A call to `npm run test:unit:php` will automatically setup a `wp-env` powered WordPress instance, already prepared to mount GatherPress from the current directory. + +So while there is no technical need to start `wp-env` manually on its own, you might want to do so for any reason. If the environment is already running, the unit tests will run against that existing instance. You might want to start it with this command: + + +```bash +npm run wp-env -- start +``` + +The testing website is reachable at `http://127.0.0.1:8889`, the user is `admin` and the password is `password`. + +### Run the unit tests + +To run the full suite with all unit tests, use the command: + +```bash +npm run test:unit:php +``` + +To run only specific tests, you can call `npm run test:unit:php`: + +- with the `--filter` argument, + to execute all tests in `test/unit/php/includes/core/classes/class-test-event-query.php` for example: + + ```bash + npm run test:unit:php -- --filter 'Test_Event_Query' + ``` + +- with the `--group` argument, to execute all tests which share the same `@group` declaration, for example all tests related to `/ical` and `/feed/ical` endpoints of events & venues: + + ```bash + npm run test:unit:php -- --group endpoints + ``` + +- or with any other of [phpunit's command-line options](https://docs.phpunit.de/en/10.5/textui.html#command-line-options). + +## Resources + +### PMC Unit Test Framework + +GatherPress uses the *PMC Unit Test Framework* because it: + +> [...] provide[s] common utilities and data mocking for unit tests in a WordPress environment. + +> This plugin was originally written for internal use at Penske Media [...] Our hope is that other teams find this plugin as useful as we do when writing unit tests in WordPress. +> +> https://github.com/penske-media-corp/pmc-unit-test + +* [Installation](https://github.com/penske-media-corp/pmc-unit-test/tree/main?tab=readme-ov-file#installation) +* [Usage](https://github.com/penske-media-corp/pmc-unit-test/tree/main?tab=readme-ov-file#usage) +* [Data Mocking Overview](https://github.com/penske-media-corp/pmc-unit-test/blob/main/src/mocks/README.md) + * [$this->mock->http()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-http.md) + * [$this->mock->input()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-input.md) + * [$this->mock->mail()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-mail.md) + * [$this->mock->post()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-post.md) + * [$this->mock->post()->is_amp()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-post.md) + * [$this->mock->user()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-user.md) + * [$this->mock->wp()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-wp.md) \ No newline at end of file From 3e4bf7e7ea5066d987a1fcc236c3bf9803549dea Mon Sep 17 00:00:00 2001 From: Carsten Bach Date: Fri, 27 Sep 2024 23:38:51 +0200 Subject: [PATCH 2/3] Fix port number for wp-env --- docs/developer/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/README.md b/docs/developer/README.md index 96c35b6e2..286b36c27 100644 --- a/docs/developer/README.md +++ b/docs/developer/README.md @@ -65,7 +65,7 @@ cd gatherpress wp-env start ``` -You should then see that a development site has been configured for you on localhost port 2003 +You should then see that a development site has been configured for you on localhost port 8889 ![Development Site Login](../media/wp-env.json-startup.png) From ad87d1fe19e22dd3a0ce29ee9af6c24af0e27502 Mon Sep 17 00:00:00 2001 From: Carsten Bach Date: Fri, 27 Sep 2024 23:50:05 +0200 Subject: [PATCH 3/3] Add & use "--fix" script for md:docs --- docs/contributor/unit-tests/README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/contributor/unit-tests/README.md b/docs/contributor/unit-tests/README.md index 4edbfed87..b33309d0f 100644 --- a/docs/contributor/unit-tests/README.md +++ b/docs/contributor/unit-tests/README.md @@ -75,15 +75,15 @@ GatherPress uses the *PMC Unit Test Framework* because it: > This plugin was originally written for internal use at Penske Media [...] Our hope is that other teams find this plugin as useful as we do when writing unit tests in WordPress. > -> https://github.com/penske-media-corp/pmc-unit-test - -* [Installation](https://github.com/penske-media-corp/pmc-unit-test/tree/main?tab=readme-ov-file#installation) -* [Usage](https://github.com/penske-media-corp/pmc-unit-test/tree/main?tab=readme-ov-file#usage) -* [Data Mocking Overview](https://github.com/penske-media-corp/pmc-unit-test/blob/main/src/mocks/README.md) - * [$this->mock->http()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-http.md) - * [$this->mock->input()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-input.md) - * [$this->mock->mail()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-mail.md) - * [$this->mock->post()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-post.md) - * [$this->mock->post()->is_amp()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-post.md) - * [$this->mock->user()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-user.md) - * [$this->mock->wp()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-wp.md) \ No newline at end of file +> + +- [Installation](https://github.com/penske-media-corp/pmc-unit-test/tree/main?tab=readme-ov-file#installation) +- [Usage](https://github.com/penske-media-corp/pmc-unit-test/tree/main?tab=readme-ov-file#usage) +- [Data Mocking Overview](https://github.com/penske-media-corp/pmc-unit-test/blob/main/src/mocks/README.md) + - [$this->mock->http()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-http.md) + - [$this->mock->input()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-input.md) + - [$this->mock->mail()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-mail.md) + - [$this->mock->post()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-post.md) + - [$this->mock->post()->is_amp()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-post.md) + - [$this->mock->user()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-user.md) + - [$this->mock->wp()](https://github.com/penske-media-corp/pmc-unit-test/blob/main/docs/mock-wp.md)