Build/Test Tools: Add script for generating code coverage report.

This adds documentation for how to generate code coverage reports to the README.md file.

`test:coverage` has also been added as an npm script to make it easier to generate a report using the local Docker environment. The script will generate an HTML, PHP, and text report file.

Props pbearne, hellofromTonya, netweb.
Fixes #53414.

git-svn-id: https://develop.svn.wordpress.org/trunk@59356 602fd350-edb4-49c9-b593-d223f7449a82

.gitignore

@@ -42,6 +42,7 @@ wp-tests-config.php
 /packagehash.txt
 /artifacts
 /setup.log
+/coverage
 
 # Files and folders that get created in wp-content
 /src/wp-content/blogs.dir

README.md

@@ -94,6 +94,19 @@ npm run test:php -- --filter <test name>
 npm run test:php -- --group <group name or ticket number>
 ```
 
+#### Generating a code coverage report
+PHP code coverage reports are [generated daily](https://github.com/WordPress/wordpress-develop/actions/workflows/test-coverage.yml) and [submitted to Codecov.io](https://app.codecov.io/gh/WordPress/wordpress-develop).
+
+After the local Docker environment has [been installed and started](#to-start-the-development-environment-for-the-first-time), the following command can be used to generate a code coverage report. 
+
+```
+npm run test:coverage
+```
+
+The command will generate three coverage reports in HTML, PHP, and text formats, saving them in the `coverage` folder.
+
+**Note:** xDebug is required to generate a code coverage report, which can slow down PHPUnit significantly. Passing selection-based options such as `--group` or `--filter` can decrease the overall time required but will result in an incomplete report.
+
 #### To restart the development environment
 
 You may want to restart the environment if you've made changes to the configuration in the `docker-compose.yml` or `.env` files. Restart the environment with:

package.json

@@ -190,6 +190,7 @@
 		"env:pull": "node ./tools/local-env/scripts/docker.js pull",
 		"test:performance": "wp-scripts test-playwright --config tests/performance/playwright.config.js",
 		"test:php": "node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit",
+		"test:coverage": "npm run test:php -- --coverage-html ./coverage/html/ --coverage-php ./coverage/php/report.php --coverage-text=./coverage/text/report.txt",
 		"test:e2e": "wp-scripts test-playwright --config tests/e2e/playwright.config.js",
 		"test:visual": "wp-scripts test-playwright --config tests/visual-regression/playwright.config.js",
 		"sync-gutenberg-packages": "grunt sync-gutenberg-packages",

tools/local-env/scripts/docker.js

@@ -7,5 +7,10 @@ dotenvExpand.expand( dotenv.config() );
 
 const composeFiles = local_env_utils.get_compose_files();
 
+if (process.argv.includes('--coverage-html')) {
+	process.env.LOCAL_PHP_XDEBUG = 'true';
+	process.env.LOCAL_PHP_XDEBUG_MODE = 'coverage';
+}
+
 // Execute any docker compose command passed to this script.
 execSync( 'docker compose ' + composeFiles + ' ' + process.argv.slice( 2 ).join( ' ' ), { stdio: 'inherit' } );