Add query API parameters and Playground CLI setup to testing with WordPress Playground

[ozgursar]

This PR adds documentation on how to test WordPress Core Trac tickets using WordPress Playground, covering both the browser-based and Playground CLI workflows.

What's included:

• How to find and use the Playground test link from a GitHub PR comment
• How to configure Playground via Query API parameters (PHP version, WP version, Gutenberg branch, multisite, etc.)
• How to install and run Playground CLI against a locally cloned wordpress-develop repository
• Optional alias setup for macOS (zsh/bash) and Windows (PowerShell) to simplify the CLI command

[ozgursar]

Can anyone using Windows help me with testing the Alias setup with Powershell (and edit if necessary)?

[3kori]

Tried the Alias setup in Windows. It works just fine.

But users might encounter an error when calling the alias:

npm error code ENOENT
npm error syscall lstat
npm error path C:\Users\Githinji\AppData\Roaming\npm
npm error errno -4058
npm error enoent ENOENT: no such file or directory, lstat 'C:\Users\Githinji\AppData\Roaming\npm'
npm error enoent This is related to npm not being able to find a file.
npm error enoent
npm error A complete log of this run can be found in: C:\Users\Githinji\AppData\Local\npm-cache\_logs\2026-04-04T16_26_02_652Z-debug-0.log

They need to create an npm folder in C:/Users/Name/AppData/Roaming.
Also, when running . $PROFILE to reload it, they might get:

. : File
C:\Users\Githinji\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
cannot be loaded because running scripts is disabled on this system. For more
information, see about_Execution_Policies at
https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:3
+ . $PROFILE
+   ~~~~~~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

This error might make users think there is something wrong, but this doesn't interfere with the execution of our code. I propose instead of using . $PROFILE to reload, users can close PowerShell and reopen it so that the alias can be active.

[3kori]

You could also include how to test patches after setting up Playground CLI against WordPress Develop.

[ozgursar]

They need to create an npm folder in C:/Users/Name/AppData/Roaming.

Thanks @3kori, I provided more detailed steps based on your feedback. Please check once again.

You could also include how to test patches after setting up Playground CLI against WordPress Develop.

I thought about this. Since we already have pages about how to test patch using WordPress Develop, wouldn't it be repetition? Is there anything specific to Playground CLI?

[3kori]

I thought about this. Since we already have pages about how to test patch using WordPress Develop, wouldn't it be repetition? Is there anything specific to Playground CLI?

The workflow for testing patches in Playground CLI from testing in WordPress Develop in Docker is different. That's why I think you should show the difference in processes.

I haven't tested patches using Playground CLI. I'll try it today and update here.

What I was thinking is, do you have to shut down the current Playground instance, rerun npm run build, and play-start again?
Or will the changes be updated without doing all this?

Edit

After a bit of testing:

1. No, you don't need to shut down the current Playground instance after applying a patch, just refresh it or hard refresh in case of a caching issue.
2. Yes, you do need to rerun npm run build after applying patches.
3. From @SirLouen video, he mentions using npm run watch to have a continuous build. But when applying patches with PHP, this wasn't the case, and I still needed to use npm run build. From my research, npm run watch is supposed to detect changes in CSS and JS files and then automatically rebuild. In my case, this didn't work (feel free to try it on your end) after applying a CSS patch, and I still needed to use npm run build for the changes to take effect.
4. No, changes don't update automatically.
5. Also, you don't need to rerun npm install after applying changes, unless changes affect package.json or package.lock.json.
6. I would point them to how to apply patches, then lead them to this other process of building changes.

[ozgursar]

Thanks @3kori for testing the build process with the Playground CLI. I've added your instructions in a separate section under the document.

[nikunj8866]

Thanks @ozgursar for working on this.

This looks good to me overall. The steps are clear and well-structured, especially the sections covering Playground usage and CLI setup.

I’ve also verified the Playground CLI setup using PowerShell, and it’s working properly as per the provided instructions.

Just a minor suggestion: "Steps instructions" sounds a bit off grammatically. Instead, you could use "Step-by-step instructions" (or similar phrasing) to improve readability.

[ozgursar]

Thanks @ozgursar for working on this.

This looks good to me overall. The steps are clear and well-structured, especially the sections covering Playground usage and CLI setup.

I’ve also verified the Playground CLI setup using PowerShell, and it’s working properly as per the provided instructions.

Just a minor suggestion: "Steps instructions" sounds a bit off grammatically. Instead, you could use "Step-by-step instructions" (or similar phrasing) to improve readability.

Thanks for reviewing @nikunj8866 and testing the PowerShell setup.
I fixed the wording of "Steps instructions" and slightly changed the wording on the previous line as well.

[nikunj8866]

LGTM!

[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: ozgursar <ozgursar@git.wordpress.org>
Co-authored-by: 3kori <r1k0@git.wordpress.org>
Co-authored-by: huzaifaalmesbah <huzaifaalmesbah@git.wordpress.org>
Co-authored-by: nikunj8866 <nikunj8866@git.wordpress.org>
Co-authored-by: ankitguptaindia <ankit-k-gupta@git.wordpress.org>
Co-authored-by: Successfulsebunya <mosescursor@git.wordpress.org>
Co-authored-by: ironprogrammer <ironprogrammer@git.wordpress.org>

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