Build/Test Tools: Improve dev environment's CLI in speed, non-interactive usage, and argument handling #8969

westonruter · 2025-06-13T00:01:44Z

Build/Test Tools: Improve dev environment's CLI in speed, non-interactive usage, and argument handling.

Start cli container when running env:start. This greatly speeds up calls to WP-CLI since the container is already running rather than having to start up for each call.
Facilitate calls to env:cli in non-interactive context (non-TTY) to allow piping content into commands or use in shell scripts.
Fix passing arguments to WP-CLI from env:cli so that arguments with spaces are passed as expected.
Fix JSHint issues.

This aligns the wordpress-develop environment closer to wp-env. See WordPress/gutenberg#50007.

Props westonruter, jorbin, SirLouen, sandeepdahiya.
Fixes #63564.

Trac ticket: https://core.trac.wordpress.org/ticket/63564

Running `env:install`

Before

$ time npm run env:install

> [email protected] env:install
> node ./tools/local-env/scripts/install.js

[+] Creating 2/2
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
Success: Generated 'wp-config.php' file.
[+] Creating 2/2
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
Success: Updated the constant 'WP_DEBUG' in the 'wp-config.php' file with the raw value 'true'.
[+] Creating 2/2
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
Success: Added the constant 'WP_DEBUG_LOG' to the 'wp-config.php' file with the raw value 'true'.
[+] Creating 2/2
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
Success: Added the constant 'WP_DEBUG_DISPLAY' to the 'wp-config.php' file with the raw value 'true'.
[+] Creating 2/2
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
Success: Added the constant 'SCRIPT_DEBUG' to the 'wp-config.php' file with the raw value 'true'.
[+] Creating 2/2
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
Success: Added the constant 'WP_ENVIRONMENT_TYPE' to the 'wp-config.php' file with the value 'local'.
[+] Creating 2/2
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
Success: Added the constant 'WP_DEVELOPMENT_MODE' to the 'wp-config.php' file with the value 'core'.
[+] Creating 2/2
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
Success: Database reset.
[+] Creating 2/2
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
Success: WordPress installed successfully.

real    0m14.993s
user    0m0.681s
sys     0m0.399s

After

$ time npm run env:install

> [email protected] env:install
> node ./tools/local-env/scripts/install.js

Success: Generated 'wp-config.php' file.
Success: Updated the constant 'WP_DEBUG' in the 'wp-config.php' file with the raw value 'true'.
Success: Added the constant 'WP_DEBUG_LOG' to the 'wp-config.php' file with the raw value 'true'.
Success: Added the constant 'WP_DEBUG_DISPLAY' to the 'wp-config.php' file with the raw value 'true'.
Success: Added the constant 'SCRIPT_DEBUG' to the 'wp-config.php' file with the raw value 'true'.
Success: Added the constant 'WP_ENVIRONMENT_TYPE' to the 'wp-config.php' file with the value 'local'.
Success: Added the constant 'WP_DEVELOPMENT_MODE' to the 'wp-config.php' file with the value 'core'.
Success: Database reset.
Success: WordPress installed successfully.

real    0m4.018s
user    0m0.598s
sys     0m0.334s

Running a single WP-CLI command

Before

$ time npm run env:cli post list

> [email protected] env:cli
> node ./tools/local-env/scripts/docker.js run --rm cli post list

[+] Creating 2/2
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
+----+--------------+-------------+---------------------+-------------+
| ID | post_title   | post_name   | post_date           | post_status |
+----+--------------+-------------+---------------------+-------------+
| 1  | Hello world! | hello-world | 2025-06-09 22:03:24 | publish     |
+----+--------------+-------------+---------------------+-------------+

real    0m2.074s
user    0m0.125s
sys     0m0.108s

After

$ time npm run env:cli post list

> [email protected] env:cli
> node ./tools/local-env/scripts/docker.js exec cli wp --allow-root post list

+----+--------------+-------------+---------------------+-------------+
| ID | post_title   | post_name   | post_date           | post_status |
+----+--------------+-------------+---------------------+-------------+
| 1  | Hello world! | hello-world | 2025-06-09 22:03:24 | publish     |
+----+--------------+-------------+---------------------+-------------+

real    0m0.682s
user    0m0.126s
sys     0m0.059s

Passing an argument with spaces to WP-CLI

Before

$ time npm --silent run env:cli option set blogname "WordPress Develop"
[+] Creating 2/2
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
Error: Too many positional arguments: Develop


real    0m1.818s
user    0m0.137s
sys     0m0.071s

After

$ time npm --silent run env:cli option set blogname "WordPress Develop"
Success: Value passed for 'blogname' option is unchanged.

real    0m0.773s
user    0m0.117s
sys     0m0.095s

Passing data to WP-CLI via STDIN

Before

$ echo "WP Develop" | time npm --silent run env:cli -- option set blogname 
[+] Creating 2/2
 ✔ Container wordpress-develop-mysql-1  Running                                                                                                                                0.0s 
 ✔ Container wordpress-develop-php-1    Running                                                                                                                                0.0s 
the input device is not a TTY
        0.22 real         0.12 user         0.05 sys

After

$ echo "WP Develop" | time npm --silent run env:cli -- option set blogname
Success: Updated 'blogname' option.
        0.81 real         0.11 user         0.09 sys

Calling WP-CLI from shell script

Given a watch.sh script that runs PHP unit tests for the comment group whenever a couple of the comments PHP files are modified:

fswatch tests/phpunit/tests/comment/commentForm.php src/wp-includes/comment-template.php | while read -r modified_file; do
	clear
	echo "Modified file: $modified_file"
	npm --silent run test:php -- --group=comment
done

Before

$ ./watch.sh
Modified file: /Users/westonruter/repos/wordpress-develop/tests/phpunit/tests/comment/commentForm.php
the input device is not a TTY

After

$ ./watch.sh
Modified file: /Users/westonruter/repos/wordpress-develop/tests/phpunit/tests/comment/commentForm.php
Installing...
Running as single site... To run multisite, use -c tests/phpunit/multisite.xml
Not running ajax tests. To execute these, use --group ajax.
Not running ms-files tests. To execute these, use --group ms-files.
Not running external-http tests. To execute these, use --group external-http.
PHPUnit 9.6.23 by Sebastian Bergmann and contributors.

Warning:       Your XML configuration validates against a deprecated schema.
Suggestion:    Migrate your XML configuration using "--migrate-configuration"!

...............................................................  63 / 510 ( 12%)
............................................................... 126 / 510 ( 24%)
............................................................... 189 / 510 ( 37%)
............................................................... 252 / 510 ( 49%)
............................................................... 315 / 510 ( 61%)
............................................................... 378 / 510 ( 74%)
............................................................... 441 / 510 ( 86%)
............................................................... 504 / 510 ( 98%)
......                                                          510 / 510 (100%)

Time: 00:03.489, Memory: 195.00 MB

OK (510 tests, 1260 assertions)

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2025-06-13T00:01:56Z

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter.

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

westonruter · 2025-06-13T00:11:19Z

package.json

 		"env:reset": "node ./tools/local-env/scripts/docker.js down --rmi all -v --remove-orphans",
 		"env:install": "node ./tools/local-env/scripts/install.js",
-		"env:cli": "node ./tools/local-env/scripts/docker.js run --rm cli",
+		"env:cli": "node ./tools/local-env/scripts/docker.js exec cli wp --allow-root",


Why --allow-root? This is done when using run: https://github.com/WordPress/wpdev-docker-images/blob/becc6740684d6ff6414d6539df040633b5ac5794/templates/Dockerfile-cli.template#L18-L24

And the entrypoint is using sudo: https://github.com/WordPress/wpdev-docker-images/blob/becc6740684d6ff6414d6539df040633b5ac5794/entrypoint/entrypoint-cli.sh#L16-L17

westonruter · 2025-06-13T00:14:54Z

.github/workflows/reusable-test-local-docker-environment-v1.yml


      - name: Test a CLI command
-        run: npm run env:cli wp option get siteurl
+        run: npm run env:cli option get siteurl


The wp is removed here because previously the entrypoint would inject it if it was missing: https://github.com/WordPress/wpdev-docker-images/blob/becc6740684d6ff6414d6539df040633b5ac5794/entrypoint/entrypoint-cli.sh#L16-L17

With this PR, the wp is always assumed.

Since this is technically a breaking change, I searched github for npm run env:cli wp and there is only one reference which seems to be from a fork of a demo rather than actual production code, but it still might be worth a PR there after this lands and a quick note in the core room so folks are aware. I don't think it needs a dev note though since this isn't a public API.

PR opened: Antonin06/wc-bretagne-2024#1

github-actions · 2025-06-13T00:21:21Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

This reverts commit ec71151.

This reverts commit 1ce3750.

westonruter · 2025-06-13T05:56:22Z

tools/local-env/scripts/install.js

+// Since WP-CLI runs as root, the wp-config.php created above will be read-only. This needs to be writable for the sake of E2E tests.
+execSync( 'node ./tools/local-env/scripts/docker.js exec cli chmod 666 wp-config.php' );


It's not clear to me why this is needed now. Without it, E2E tests fail due to wp-config.php not being writable: https://github.com/WordPress/wordpress-develop/actions/runs/15627027244/job/44023152411

In 0e4ddbb I tried using the node API to set the file permissions, but this failed because it's not being run as root: https://github.com/WordPress/wordpress-develop/actions/runs/15624512371/job/44016093197

I think in 0e4ddbb it was running on the local filesystem whereas in this implementation it is running in the container.

aaronjorbin · 2025-06-13T16:05:44Z

.github/workflows/reusable-test-local-docker-environment-v1.yml


      - name: Test a CLI command
-        run: npm run env:cli wp option get siteurl
+        run: npm run env:cli option get siteurl


Since this is technically a breaking change, I searched github for npm run env:cli wp and there is only one reference which seems to be from a fork of a demo rather than actual production code, but it still might be worth a PR there after this lands and a quick note in the core room so folks are aware. I don't think it needs a dev note though since this isn't a public API.

aaronjorbin · 2025-06-13T16:28:17Z

tools/local-env/scripts/install.js

+// Since WP-CLI runs as root, the wp-config.php created above will be read-only. This needs to be writable for the sake of E2E tests.
+execSync( 'node ./tools/local-env/scripts/docker.js exec cli chmod 666 wp-config.php' );


I think in 0e4ddbb it was running on the local filesystem whereas in this implementation it is running in the container.

SirLouen · 2025-06-13T17:17:02Z

docker-compose.yml

      - ./:/var/www

+    # Keeps the service alive.
+    command: 'sleep infinity'


For a true idling container I would rather use
command: 'tail -f /dev/null'

I chose this for consistency with wp-env.

It seems there were no big explanations
WordPress/gutenberg@c11312a

If Gutenberg switches back to tail we can switch it back here too.

SirLouen · 2025-06-13T17:21:13Z

docker-compose.yml

      - ./:/var/www

+    # Keeps the service alive.
+    command: 'sleep infinity'


It seems there were no big explanations
WordPress/gutenberg@c11312a

github-actions · 2025-06-13T23:02:13Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 60308
GitHub commit: 3a09159

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

westonruter added 8 commits June 12, 2025 14:03

Fix JSHint issues

a3cf770

Keep cli service running to speed up WP-CLI commands

23ac059

Reuse env:cli in wp_cli command in env:install

6b3de67

Fix jshint by declaring node env

7a66e62

Use spawnSync to ensure args with spaces are passed properly

b8b1425

Apply prettier formatting to docker.js

f4d6575

Remove obsolete try/catch since spawnSync is used

bcbf5da

Fix running Docker when not in TTY

3e2fa2e

westonruter requested a review from aaronjorbin June 13, 2025 00:01

Remove extraneous wp from GHA workflow

8f2af97

westonruter commented Jun 13, 2025

View reviewed changes

westonruter added 6 commits June 12, 2025 18:40

Simplify path to wp-config.php and ensure writable for E2E tests

0e4ddbb

Make wp-config.php writable from inside container

12b4457

Try removing chmod 666 wp-config.php

1ce3750

Try reverting change to wp_cli()

ec71151

Revert "Try reverting change to wp_cli()"

45954e9

This reverts commit ec71151.

Revert "Try removing chmod 666 wp-config.php"

1b2ef30

This reverts commit 1ce3750.

westonruter commented Jun 13, 2025

View reviewed changes

aaronjorbin approved these changes Jun 13, 2025

View reviewed changes

SirLouen reviewed Jun 13, 2025

View reviewed changes

SirLouen approved these changes Jun 13, 2025

View reviewed changes

github-actions bot closed this Jun 13, 2025

This was referenced Jun 13, 2025

Remove extraneous wp in env:cli command Antonin06/wc-bretagne-2024#1

Open

Allow multiple config values to be set at once wp-cli/config-command#199

Open

		// Since WP-CLI runs as root, the wp-config.php created above will be read-only. This needs to be writable for the sake of E2E tests.
		execSync( 'node ./tools/local-env/scripts/docker.js exec cli chmod 666 wp-config.php' );

Build/Test Tools: Improve dev environment's CLI in speed, non-interactive usage, and argument handling #8969

Build/Test Tools: Improve dev environment's CLI in speed, non-interactive usage, and argument handling #8969

Conversation

westonruter commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Running env:install

Before

After

Running a single WP-CLI command

Before

After

Passing an argument with spaces to WP-CLI

Before

After

Passing data to WP-CLI via STDIN

Before

After

Calling WP-CLI from shell script

Before

After

Uh oh!

github-actions bot commented Jun 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jun 13, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jun 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

westonruter commented Jun 13, 2025 •

edited

Loading

Running `env:install`