From f234090794408f41673888c24292f0ca321c1d52 Mon Sep 17 00:00:00 2001 From: "Md. Arifur Rahman" Date: Fri, 2 Oct 2026 11:00:10 +0600 Subject: [PATCH 1/3] Document why NodeJS is needed to run the tests Explains that the build step downloads the pinned Gutenberg artifact from ghcr.io and copies the block editor files into src/, which the tests load. Also notes engine-strict and that the production build is not needed for PHPUnit. Fixes #243. Co-Authored-By: Claude Opus 5.5 --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 4302671..1ad1a37 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,22 @@ nodejs --version npm --version ``` +#### Why NodeJS is needed + +The PHPUnit tests are PHP, but they do not run on a plain checkout of `wordpress-develop`. Some files that WordPress loads are not in version control. A build step creates them. + +`prepare.php` runs `npm install && npm run build` in the checkout. For the tests, the important part is the Gutenberg step (`build:gutenberg` in the [Gruntfile](https://github.com/WordPress/wordpress-develop/blob/trunk/Gruntfile.js)): + +1. It downloads the built Gutenberg artifact for the version pinned in `package.json` (`gutenberg.sha`). The download comes from `ghcr.io`, so the server must be able to connect to it. +2. It copies the block editor PHP files, routes, blocks, scripts, styles and `theme.json` into `src/`. + +The tests load WordPress from `src/` (`ABSPATH` in `wp-tests-config.php`). These files were removed from version control in [changeset 61438](https://core.trac.wordpress.org/changeset/61438). Without the build, the tests fail when they load WordPress, for example on a missing `src/wp-includes/build/routes.php` ([#292](https://github.com/WordPress/phpunit-test-runner/issues/292)). + +Also: + +- Use the Node.js and npm versions in the `engines` field of `wordpress-develop/package.json`. Its `.npmrc` sets `engine-strict = true`, so `npm install` stops on older versions. +- `npm run build` also makes the production build: it copies files to `build/` and minifies JavaScript and CSS. The PHPUnit tests do not use these files. WordPress Core runs its own PHPUnit workflow after `npm ci` and `npm run build:dev`. [#244](https://github.com/WordPress/phpunit-test-runner/issues/244) tracks ways to make this step smaller. + ### PHP Composer _This is a simple example for Debian / Ubuntu._ From 363246467afc7b716fc943527e82c329d5d8786c Mon Sep 17 00:00:00 2001 From: "Md. Arifur Rahman" Date: Fri, 2 Oct 2026 22:55:34 +0600 Subject: [PATCH 2/3] Rework the Node.js section after review Make it a standalone ### section, open with why a PHP suite needs Node.js, list the Gutenberg steps in order, and add a summary sentence (from the review). Keep the ghcr.io network requirement, the changeset and issue references, and the build:dev note. Mention that devEngines also enforces the npm version. --- README.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 1ad1a37..6f755f2 100644 --- a/README.md +++ b/README.md @@ -130,21 +130,27 @@ nodejs --version npm --version ``` -#### Why NodeJS is needed +### Why Node.js is needed -The PHPUnit tests are PHP, but they do not run on a plain checkout of `wordpress-develop`. Some files that WordPress loads are not in version control. A build step creates them. +The PHPUnit tests are written in PHP, but `prepare.php` needs Node.js and npm to prepare the WordPress checkout before the tests can run. -`prepare.php` runs `npm install && npm run build` in the checkout. For the tests, the important part is the Gutenberg step (`build:gutenberg` in the [Gruntfile](https://github.com/WordPress/wordpress-develop/blob/trunk/Gruntfile.js)): +The tests load WordPress from `src/` (`ABSPATH` in `wp-tests-config.php`). Some files that WordPress loads from there are not in version control: they were removed in [changeset 61438](https://core.trac.wordpress.org/changeset/61438), and the build creates them. -1. It downloads the built Gutenberg artifact for the version pinned in `package.json` (`gutenberg.sha`). The download comes from `ghcr.io`, so the server must be able to connect to it. -2. It copies the block editor PHP files, routes, blocks, scripts, styles and `theme.json` into `src/`. +`prepare.php` runs `npm install && npm run build`. For the tests, the important part is the Gutenberg step (`build:gutenberg` in the [Gruntfile](https://github.com/WordPress/wordpress-develop/blob/trunk/Gruntfile.js)): -The tests load WordPress from `src/` (`ABSPATH` in `wp-tests-config.php`). These files were removed from version control in [changeset 61438](https://core.trac.wordpress.org/changeset/61438). Without the build, the tests fail when they load WordPress, for example on a missing `src/wp-includes/build/routes.php` ([#292](https://github.com/WordPress/phpunit-test-runner/issues/292)). +1. It uses the Gutenberg version that WordPress pins in `package.json` (`gutenberg.sha`). +2. It downloads the pre-built Gutenberg artifact for that version from GitHub Container Registry (`ghcr.io`). The server must be able to connect to `ghcr.io`. +3. It copies the block editor PHP files, routes, blocks, scripts, styles and `theme.json` into `src/`. -Also: +If this step does not run, the tests fail while WordPress loads, for example on a missing `src/wp-includes/build/routes.php` ([#292](https://github.com/WordPress/phpunit-test-runner/issues/292)). This is why Node.js and npm are requirements, even though the tests are PHP. -- Use the Node.js and npm versions in the `engines` field of `wordpress-develop/package.json`. Its `.npmrc` sets `engine-strict = true`, so `npm install` stops on older versions. -- `npm run build` also makes the production build: it copies files to `build/` and minifies JavaScript and CSS. The PHPUnit tests do not use these files. WordPress Core runs its own PHPUnit workflow after `npm ci` and `npm run build:dev`. [#244](https://github.com/WordPress/phpunit-test-runner/issues/244) tracks ways to make this step smaller. +Versions: + +- Use the Node.js and npm versions in the `engines` field of `wordpress-develop/package.json`. Its `.npmrc` sets `engine-strict = true`, and `devEngines` also requires the npm version, so `npm install` stops on older versions. + +Extra work: + +- `npm run build` does more than PHPUnit needs. It also makes the production build in `build/` and minifies JavaScript and CSS. The tests do not use these files. WordPress Core runs its own PHPUnit workflow after `npm ci` and `npm run build:dev`. [#244](https://github.com/WordPress/phpunit-test-runner/issues/244) tracks ways to make this step smaller. ### PHP Composer From 148566c3a0f601f1ce4a715da2e339b4462404d0 Mon Sep 17 00:00:00 2001 From: "Md. Arifur Rahman" Date: Tue, 6 Oct 2026 19:46:34 +0600 Subject: [PATCH 3/3] Use the reviewed wording for the Node.js section Base the section on the wording suggested in review, and use real headings for Versions and Extra work (review suggestions). Keep the facts hosts need: the build commands, changeset 61438, gutenberg.sha, the ghcr.io connection, the routes.php example, devEngines with the EBADDEVENGINES error, and Core's build:dev workflow. --- README.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 6f755f2..f7a5d9f 100644 --- a/README.md +++ b/README.md @@ -132,25 +132,28 @@ npm --version ### Why Node.js is needed -The PHPUnit tests are written in PHP, but `prepare.php` needs Node.js and npm to prepare the WordPress checkout before the tests can run. +The PHPUnit test suite itself is written in PHP, but Node.js is required to prepare the WordPress source code before the tests can run. -The tests load WordPress from `src/` (`ABSPATH` in `wp-tests-config.php`). Some files that WordPress loads from there are not in version control: they were removed in [changeset 61438](https://core.trac.wordpress.org/changeset/61438), and the build creates them. +The test runner uses `prepare.php` to set up a WordPress checkout and prepare it for PHPUnit. As part of this process, it runs the WordPress build tasks (`npm install && npm run build`), including the Gutenberg build step (`build:gutenberg` in the [Gruntfile](https://github.com/WordPress/wordpress-develop/blob/trunk/Gruntfile.js)). This is necessary because some files used by WordPress Core are generated or assembled as part of the build process rather than being available directly in the `wordpress-develop` checkout. These files were removed from version control in [changeset 61438](https://core.trac.wordpress.org/changeset/61438). -`prepare.php` runs `npm install && npm run build`. For the tests, the important part is the Gutenberg step (`build:gutenberg` in the [Gruntfile](https://github.com/WordPress/wordpress-develop/blob/trunk/Gruntfile.js)): +The Gutenberg build step: -1. It uses the Gutenberg version that WordPress pins in `package.json` (`gutenberg.sha`). -2. It downloads the pre-built Gutenberg artifact for that version from GitHub Container Registry (`ghcr.io`). The server must be able to connect to `ghcr.io`. -3. It copies the block editor PHP files, routes, blocks, scripts, styles and `theme.json` into `src/`. +1. Uses the Gutenberg version pinned by WordPress Core (`gutenberg.sha` in `package.json`). +2. Downloads the corresponding pre-built Gutenberg artifact from GitHub Container Registry (`ghcr.io`), so the server must be able to connect to `ghcr.io`. +3. Copies the required Gutenberg files into the WordPress `src/` directory. +4. Makes those files available to the WordPress installation that PHPUnit loads during the test run. -If this step does not run, the tests fail while WordPress loads, for example on a missing `src/wp-includes/build/routes.php` ([#292](https://github.com/WordPress/phpunit-test-runner/issues/292)). This is why Node.js and npm are requirements, even though the tests are PHP. +The PHPUnit test suite loads WordPress from the `src/` directory. Therefore, these build steps must complete successfully before the tests can run. If the Gutenberg files have not been prepared, the test suite can fail while loading WordPress because required files are missing, for example `src/wp-includes/build/routes.php` ([#292](https://github.com/WordPress/phpunit-test-runner/issues/292)). -Versions: +This is why Node.js and npm are requirements for the test runner even though the tests themselves are written in PHP. -- Use the Node.js and npm versions in the `engines` field of `wordpress-develop/package.json`. Its `.npmrc` sets `engine-strict = true`, and `devEngines` also requires the npm version, so `npm install` stops on older versions. +#### Versions -Extra work: +The Node.js and npm versions must be compatible with the versions specified in the `engines` and `devEngines` fields of `wordpress-develop/package.json`. Because of these fields and the repository's `engine-strict` npm setting, using an unsupported Node.js or npm version causes `npm install` to fail, for example with `npm error code EBADDEVENGINES`. -- `npm run build` does more than PHPUnit needs. It also makes the production build in `build/` and minifies JavaScript and CSS. The tests do not use these files. WordPress Core runs its own PHPUnit workflow after `npm ci` and `npm run build:dev`. [#244](https://github.com/WordPress/phpunit-test-runner/issues/244) tracks ways to make this step smaller. +#### Extra work + +`npm run build` performs more work than is required by PHPUnit. The complete WordPress build also creates the production `build/` directory and performs tasks such as JavaScript and CSS minification. The PHPUnit tests primarily need the files prepared in `src/`. The additional build work is currently part of the preparation process. WordPress Core's own PHPUnit workflow runs `npm ci` and `npm run build:dev` instead, and [#244](https://github.com/WordPress/phpunit-test-runner/issues/244) tracks ways to make this step smaller. ### PHP Composer