test-core-tickets-with-playground.md

Test Core Tickets with Playground

WordPress Playground is an online platform that lets you experiment and learn about WordPress without affecting your live website. It’s a virtual sandbox where you can test features, designs, and settings in a safe and controlled environment. More about WordPress Playground can be read here.

How to Test Core Tickets with Playground

1. Go to the Trac ticket and check that the ticket has a GitHub PR or a patch file. If a ticket has PR, you can test that Trac ticket with Playground. If the Trac ticket has “.patch”. This automatic test environment will not work.

   

2. Click on the ‘View PR’ button, it will open the respective GitHub PR as shown in the screenshot below.

   

3. On the PR comment thread, it will find the GitHub action default comment about ‘Test using WordPress Playground’

   

4. You will find a link with the text ‘Test this pull request with WordPress Playground’. Click on this link. It will create a disposable WordPress website with the changes implemented in the PR.

   

5. Click on the ‘Go’ button if the page doesn’t redirect automatically to the WordPress site.

   

6. You will see a new WordPress site in your browser window.

   

There are some limitations to this Playground environment. You can read more here.

• All changes will be lost when a tab is closed with a Playground instance.
• All changes will be lost when refreshing the page.

In the WordPress Playground environment you can test the PR for the feature changes, bug fixes, regression issues and more.

How to Configure Playground Using Query API Parameters

If you prefer a video walkthrough, you may follow along with this video guide as you work through the instructions below.

WordPress Playground exposes a simple API that you can use to configure the Playground in the browser.

It works by passing configuration options as query API parameters to the Playground URL.

For example, to install the Test Reports plugin, you would use the following URL:

https://playground.wordpress.net/?plugin=test-reports

Similarly, by adding multiple query API parameters to the URL, you can initiate the custom Playground environment you need for testing a particular ticket.

Here are some of the parameters you can use:

• php=8.5 - To test with a specific PHP version use the exact version or the keyword latest.

• wp=trunk - Normally we test with trunk but this can be set to a specific WP version such as 6.9 or set to beta for the latest beta version.

• gutenberg-branch=trunk - To set the gutenberg branch.

• multisite=yes - To enable multisite.

• core-pr=12345 - To apply a pull request patch for Core.

• gutenberg-pr=12345 - To apply a pull request patch for Gutenberg.

For example, to initiate the Playground with WordPress trunk and PHP 8.3 you would use this link: https://playground.wordpress.net/?wp=trunk&php=8.3

How to Install and Configure Playground CLI

WordPress Playground CLI is a potential replacement for the current Docker instance for testing purposes within the Wordpress Core development scope.

You can refer to this video guide for a visual walkthrough.

Setup instructions:

1. Ensure you have WordPress Develop repository locally cloned.
2. Using your computer's terminal, access the folder of this repository.
3. Inside this folder, run npm install and then npm run build.
4. Finally, run the long npx command below:

npx @wp-playground/cli@latest server \
  --mount-before-install=./build:/wordpress \
  --wordpress-install-mode=install-from-existing-files-if-needed \
  --login \
  --site-url=http://localhost:9400 \
  --mount=./src/wp-content/plugins:/wordpress/wp-content/plugins

5. Your WordPress instance should now be accessible at: http://localhost:9400

7. Optionally, you can mount your themes folder if you will be adding code snippets into your active theme's functions.php file and want to keep the changes between rebuilds. To avoid affecting future tests, don't forget to remove any custom code snippets you have added.

Here is how you would mount the themes folder alongside the plugins.

npx @wp-playground/cli@latest server \
  --mount-before-install=./build:/wordpress \
  --wordpress-install-mode=install-from-existing-files-if-needed \
  --login \
  --site-url=http://localhost:9400 \
  --mount=./src/wp-content/plugins:/wordpress/wp-content/plugins \
  --mount=./src/wp-content/themes:/wordpress/wp-content/themes

6. You may also consider creating an alias for this long command in your terminal, so that you don't need to remember and type it every time.

How to Create an Alias in MacOS

The most common shells are Zsh and Bash. To find out which one you are using, simply open your terminal and run echo $SHELL.

This command will return /bin/zsh or /bin/bash.

Next, you need to edit your shell's run command file which is a plain text configuration file that runs automatically every time you open a new terminal session.

To edit your run command file, open your terminal and run vi ~/.zshrc and add the following to the end of the file. Or, if you are using Bash, run vi ~/.bashrc.

alias play-start='npx @wp-playground/cli@latest server \
  --mount-before-install=./build:/wordpress \
  --wordpress-install-mode=install-from-existing-files-if-needed \
  --login \
  --site-url=http://localhost:9400 \
  --mount=./src/wp-content/plugins:/wordpress/wp-content/plugins'

Here, play-start is your alias that you will be using to run the long npx command. You can choose any name that you can easily remember.

Then reload your config with one of the following commands: source ~/.zshrc if you are using Zsh or source ~/.bashrc if you are using Bash.

Now you can just run play-start from your terminal from the folder where you cloned the wordpress-develop repo.

How to Create an Alias in Windows PowerShell

The $PROFILE is the PowerShell equivalent of ~/.zshrc on Zsh. It runs automatically every time you open a PowerShell session, so it's where you add your functions, aliases, and environment variables.

To edit it, run notepad $PROFILE.

If you don't have an existing $PROFILE, you might need to run the following command first to create it:

New-Item -Path $PROFILE -ItemType File -Force

The -Force flag handles it gracefully. It creates the file (and any missing folders) if it doesn't exist, and does nothing if it already exists.

PowerShell doesn't have aliases for multi-line commands. So you need a function. Add this to your PowerShell profile:

function play-start {
  npx @wp-playground/cli@latest server `
    --mount-before-install=./build:/wordpress `
    --wordpress-install-mode=install-from-existing-files-if-needed `
    --login `
    --site-url=http://localhost:9400 `
    --mount=./src/wp-content/plugins:/wordpress/wp-content/plugins
}

Note the backtick ` instead of \ for line continuation.

Close your PowerShell and reopen it before calling your alias, which is play-start in this example.

If you get an npm error code ENOENT when calling the alias, create the npm folder inside C:/Users/yourname/AppData/Roaming and then try to run your alias again.

The Build Workflow for Testing Patches in Playground CLI

Testing patches with Playground CLI is almost same with the steps provided at the Testing Core Tickets with Grunt page.

The only difference is how to build after applying the patch.

When using Docker Desktop services, you would use npm run build:dev to apply JavaScript and CSS changes. If the patch changes only PHP files, there is no need to run npm run build:dev again.

However, since Playground CLI serves files from the build folder, which is compiled from the src folder, you need to rerun npm run build after applying the patch.

But you don't need to rerun npm install after applying changes, unless changes affect package.json or package.lock.json.

Resources

• WPContrib WordPress Test Contributor Pathway YouTube Channel by @SirLouen
• WordPress Playground Docs
• Playground CLI Docs
• PowerShell Docs for Setting Alias
• SS64 Docs for Setting Aliases and Macros