docs: add testing and debugging docs

docs/Documentation.md

@@ -8,13 +8,16 @@ Here are the main guidelines for developing redistributable PHP packages at Data
     * [Types](#types)
   * [Release Please](#release-please)
   * [Code style and formatting](#code-style-and-formatting)
+  * [Testing, debugging and code coverage](#testing-debugging-and-code-coverage)
+    * [Configuring an existing project](#configuring-an-existing-project)
+    * [Running tests](#running-tests)
 <!-- TOC -->
 
 ## Conventional Commits
 
 ✅️ All VCS commits must adhere to the Conventional Commits specification.
 
-Conventional Commits is a specification for adding human and machine readable meaning to commit messages.
+Conventional Commits is a specification for adding human and machine-readable meaning to commit messages.
 It is based on the [Semantic Versioning](https://semver.org/) specification.
 You can read more about it on [conventionalcommits.org](https://www.conventionalcommits.org/).
 
@@ -39,15 +42,15 @@ npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'
 ### Types
 This is a list with commit types and their example scopes within our packages:
 * `build`: changing files that are related to package development and distribution tools (e.g. lando, npm, vite...) and updating external dependencies (e.g. laravel/framework, league/csv...)
-* `ci`: changes for Continous integration / GitHub actions (e.g. tests, codecov, fix-code-style...)
+* `ci`: changes for Continuous integration / GitHub actions (e.g. tests, codecov, fix-code-style...)
 * `chore`: all other changes that are irrelevant to downstream (e.g. .gitignore, .editorconfig...)
 * `docs`: documentation only changes (e.g. README)
 * `feat`: adding a new feature, increases the `MINOR` number on release
 * `fix`: fixing a bug, increases the `PATCH` number on release
 * `perf`: a code change that improves performance
 * `refactor`: a code change that neither fixes a bug nor adds a feature
 * `revert`: a commit that reverts changes by a previous commit. Message should include the exact message of the reverted commit, e.g.: `revert: build(npm): add prepare script`.
-* `style`: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
+* `style`: changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
 * `test`: Adding missing tests or correcting existing tests
 
 The above is mostly copied from [Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines).
@@ -73,3 +76,52 @@ To set it up in an existing project:
     "format": "vendor/bin/pint"
 }
 ```
+
+## Testing, debugging and code coverage
+
+✅️ The package should:
+* be tested with [Pest](https://pestphp.com/),
+* have a fully integrated testing and debugging experience in the PhpStorm IDE,
+* have a high code coverage (ideally 100%, but not at the expense of the common practical sense),
+* have a CI testing workflow.
+
+Prerequisites:
+* PhpStorm
+* Pest PhpStorm plugin - to install it, go to `Settings > Plugins > Marketplace` and search for `Pest`
+
+By creating your package from this template, you will get a fully configured PhpStorm project with Pest, Xdebug and a test runner set up and ready to go.
+
+### Configuring an existing project
+1. Add Pest to the project. See the [Pest documentation](https://pestphp.com/docs/installation) for installation instructions.
+2. Configure PhpStorm for testing and debugging. This is a bit more involved, so it's described in detail on the [Testing with PhpStorm](Testing%20with%20PhpStorm.md) page. 
+3. Create a `test` script in `composer.json`:
+    ```
+    "scripts": {
+        "test": "vendor/bin/pest"
+    }
+    ```
+4. Create a `test` tooling entry in the `.lando.dist.yml` file:
+    ```
+    tooling:
+      test:
+        service: appserver
+        description: Run tests
+        cmd: composer test
+    ```
+
+### Running tests
+There are different ways to run tests:
+* Running test runners from the IDE — use the IDE buttons or keyboard shortcuts.
+* Locate a specific test in the test file and press `Alt+Enter` to run it in the IDE tool window. The IDE creates a temporary test runner for this.
+* Run tests from the CLI:
+    ```shell
+    lando test
+    ```
+    ... or when in the container (or in a CI workflow):
+    ```shell
+    composer test
+    ```
+    If you want to use the `--filter` parameter, you have to call Pest directly inside the container:
+    ```shell
+    ./vendor/bin/pest --filter=MyTest
+    ```

docs/Testing with PhpStorm.md

@@ -0,0 +1,67 @@
+Setting up a fully integrated PhpStorm testing and debugging experience consists of three main steps.
+
+Please note that despite what the Lando documentation page says, as things currently are, it's not required to add any xdebug entry to the Lando config file.
+Debugging works out of the box, as long as the instructions below are followed.
+
+## Docker connection
+Add the Docker connection, if you don't have it already:
+* Go to `Settings > Build, Execution, Deployment > Docker`
+* Click the `+` button
+* Configure the connection to your Docker daemon
+* Click `OK`
+
+Your setup might differ, but it should look something like this:
+
+[<img src="assets/img/docker-connection.png" width="500"/>](assets/img/docker-connection.png)
+
+## PHP CLI interpreter
+Set up the PHP CLI interpreter:
+* Go to `Settings > PHP`
+* Next to the `CLI Interpreter` dropdown, click the three dots  
+  [<img src="assets/img/cli-interpreter-step-1.png" width="500" style="margin: 20px 0"/>](assets/img/cli-interpreter-step-1.png)
+
+* In the new window, click the `+` button in the top left and select `From Docker, Vagrant, VM, WSL...`  
+  [<img src="assets/img/cli-interpreter-step-2.png" width="500" style="margin: 20px 0"/>](assets/img/cli-interpreter-step-2.png)
+
+* The "Configure Remote PHP Interpreter" window opens, where you need to:
+    * Select `Docker compose`, so that PhpStorm connects to the existing and running instance of the Docker container, which is already configured by the Lando config file.
+    * For `Configuration files`, set the files that Lando created in your `.lando` directory.  
+      [<img src="assets/img/cli-interpreter-compose-config.png" width="500" style="margin: 20px 0"/>](assets/img/cli-interpreter-compose-config.png)
+    * After the `Service` dropdown is populated, select `appserver`  
+      [<img src="assets/img/cli-interpreter-remote-config.png" width="400" style="margin: 20px 0"/>](assets/img/cli-interpreter-remote-config.png)
+    * That's it, press `OK`
+
+
+* You are now back at the CLI Interpreters window, where the new interpreter is now selected and more configuration options are available. Here you need to:
+    * Set a name for the interpreter. We recommend setting `Lando (docker-compose)` so it's clear that it runs through the Lando-configured container.
+    * For `Lifecycle`, select `Connect to existing container ('docker-composer exec)`.
+    * In the `Additional` fieldset, for the `Debugger extension` set the Xdebug extension.
+        * For PHP 8.1 this should be:  
+          `/usr/local/lib/php/extensions/no-debug-non-zts-20210902/xdebug.so`
+        * You can always find your correct path to `xdebug.so` by SSH-ing into the container (`lando ssh`) and running the command:  
+          `find /usr/local/lib/php/extensions -name 'xdebug.so'`
+    * If you did everything correctly, you can now click the `Reload phpinfo` button and the correct PHP/Xdebug info will be displayed.  
+      [<img src="assets/img/cli-interpreter-final-config.png" width="600" style="margin: 20px 0"/>](assets/img/cli-interpreter-final-config.png)
+
+## Set up the test runner
+This is the last step and it's the easiest one.
+
+* Open the `Run/Debug Configurations` window in the IDE. The PhpStorm UI changes frequently, but it should be somewhere in the `Run` toolbar.  
+  ![](assets/img/test-runner-configs.png)
+* In the top left corner, click the `+` button and select `Pest`.
+* The runner config will now open and here you should:
+    * Name the runner (1). "All tests" is recommended for the main test suite that includes all tests.
+    * Set `Defined in the configuration file` for the test scope (2).
+    * Set the correct CLI interpreter (3), if you have different ones (i.e. for testing in different PHP versions)
+    * Enable `Store as project file` (4) for the test runner that should be distributed to other developers and does not have any of your specific configuration options.  
+      It's a good idea to share the default runner, especially when it needs some special configuration options.  
+      If you as a developer need specifics, you should create your own runner, not share it in VCS and perhaps set `Use alternative configuration file` if you created a local `phpunit.xml` to use instead of the `phpunit.xml.dist` file that came with the package.
+    * In the end, it should end up looking something like this:  
+      [<img src="assets/img/test-runner-details.png" width="600" style="margin: 20px 0"/>](assets/img/test-runner-details.png)
+
+
+That's it! You should now be able to run tests, debug (by setting breakpoints in source code) and generate code coverage. The latter will also be visible in the Coverage tool window and also in the source code, which is nifty:
+
+![](assets/img/code-coverage-tool-window.png)
+
+![](assets/img/code-coverage-source-code.png)