Document why NodeJS is needed to run the tests

[iarif4u]

Fixes #243.

Purpose

Hosts ask why a PHP test suite needs NodeJS. This adds a short "Why NodeJS is needed" section under the NodeJS installation steps in the README.

What it explains

• prepare.php runs npm install && npm run build. The step the tests need is build:gutenberg. It downloads the pinned Gutenberg artifact from ghcr.io and copies the block editor PHP files, routes, blocks, scripts, styles and theme.json into src/.
• The tests load WordPress from src/. Those files left version control in changeset 61438, so without the build, WordPress fails to load (example: PHPUnit tests fail: routes.php generated under build/ but tests bootstrap from src/ #292).
• Hosts must allow outbound connections to ghcr.io. This is new information for firewalled hosts.
• engine-strict = true in wordpress-develop/.npmrc means that npm install stops on an older Node.js version.
• The production part of npm run build (copy to build/, minify) is not used by PHPUnit. Core's own PHPUnit workflow uses npm ci and npm run build:dev. Links to Find ways to reduce the need for NodeJS #244 for the follow-up.

Sources (wordpress-develop trunk)

• Gruntfile.js: the build, build:gutenberg and gutenberg:download tasks, and the comment that references changeset 61438 and ticket 64393
• tools/gutenberg/utils.js and download.js: version check, auto-download, ghcr.io URLs
• package.json (gutenberg.sha, engines) and .npmrc (engine-strict)
• .github/workflows/reusable-phpunit-tests-v3.yml: npm ci and npm run build:dev before PHPUnit
• wp-tests-config-sample.php: ABSPATH is src/

Contributed at WordCamp Contributor Day.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: iarif4u <iarif4u@git.wordpress.org>
Co-authored-by: dhruvang21 <dhruvang21@git.wordpress.org>
Co-authored-by: mindctrl <mindctrl@git.wordpress.org>
Co-authored-by: ekamran <ekamran@git.wordpress.org>
Co-authored-by: Crixu <crixu@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[dhruvang21]

Why Node.js is needed

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 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, including the Gutenberg build step. 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.

The Gutenberg build step:

1. Uses the Gutenberg version pinned by WordPress Core.
2. Downloads the corresponding pre-built Gutenberg artifact from GitHub Container Registry (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.

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.

This is why Node.js and npm are requirements for the test runner even though the tests themselves are written in PHP.

The Node.js and npm versions must also be compatible with the versions specified in the engines field of wordpress-develop/package.json. The WordPress development repository enables npm's engine-strict setting, so using an unsupported Node.js or npm version can cause npm install to fail.

It is also worth noting that 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.

[iarif4u]

Thanks @dhruvang21, your version reads better. I reworked the section in 3632464 and used your structure:

• A standalone ### Why Node.js is needed section, with "Node.js" spelled correctly.
• It opens with why a PHP suite needs Node.js.
• The Gutenberg steps are numbered in order, starting with the pinned version.
• It ends with your summary sentence.

I kept a few things that your text left out, because hosts need them:

• The server must reach ghcr.io. On a firewalled host, prepare.php fails there.
• The links to changeset 61438 and PHPUnit tests fail: routes.php generated under build/ but tests bootstrap from src/ #292, so readers can check why the files are missing and what the error looks like.
• Core runs PHPUnit after npm run build:dev, with a link to Find ways to reduce the need for NodeJS #244.

I also added that devEngines enforces the npm version, in addition to engine-strict. Could you take another look?

[dhruvang21]

@iarif4u The technical details here are useful, but I think the section could be improved for clarity, flow, and grammatical accuracy. Rather than making several small edits, could we replace the current section with the version suggested in the change? It keeps the technical details while making the explanation easier to follow.

[iarif4u]

@dhruvang21 Done in 148566c. The section now uses your version, with your sentences. I only added back the facts that your version left out, each as a short clause in your text:

• The build commands (npm install && npm run build) and a link to the Gruntfile.
• Changeset 61438, which removed these files from version control.
• gutenberg.sha in package.json, where the pinned version comes from.
• "the server must be able to connect to ghcr.io". Hosts with an outbound firewall need this.
• The routes.php example from PHPUnit tests fail: routes.php generated under build/ but tests bootstrap from src/ #292, so readers know what the failure looks like.
• Under Versions: devEngines and the EBADDEVENGINES error that npm shows. vairafiq got this error on Node.js 22 in Update test runner Node.js requirement to 24.x hosting-handbook#445.
• Under Extra work: Core's own PHPUnit workflow uses npm run build:dev, and Find ways to reduce the need for NodeJS #244.

I also applied @mindctrl's two heading suggestions. Could you take another look?

[mindctrl]

I think this domain redirects to pkg-containers.githubusercontent.com when downloading the package.

[iarif4u]

Good catch, confirmed. With the current pinned Gutenberg build, GET https://ghcr.io/v2/WordPress/gutenberg/gutenberg-wp-develop-build/blobs/<digest> returns 307 with Location: https://pkg-containers.githubusercontent.com/..., and download.js uses fetch(), which follows it. Step 2 now names both domains (4814a42).

Note: 4814a42 also deleted other files by mistake, because my local copy was damaged. 3a9c1e6 restores them, and the PR is back to README.md only (+25).

[ekamran]

Thanks, looks good.