How to test your first WordPress Core patch

Every WordPress release is tested by volunteers before it ships. Patch testing is one of the easiest ways to join them: you don't need to write code, only to check whether a proposed fix does what it says. This guide walks through testing your first Core patch from start to finish, whichever setup you choose.

Why patch testing matters

A ticket on Core Trac often has a patch or a linked pull request waiting for someone to confirm it works. Committers look for test reports before they commit, so a clear report from you can move a fix forward. Testing also teaches you how Core is built, which makes writing your own patches much easier later.

Choose your setup

There are three ways to test a patch. You only need one.

	Install	Tests PRs	Tests Trac .diff / .patch	Keeps your site
WordPress Playground	Nothing, it runs in your browser	Yes	No	No, closing or refreshing the tab clears it
WordPress Contributor Toolkit	One desktop app	Yes	Yes	Yes
wordpress-develop with Docker	Git, Node.js, npm and Docker	Yes	Yes	Yes

If you're new, start with Playground for a ticket that has a pull request, or the Contributor Toolkit for anything else. Use wordpress-develop with Docker when you also want to run the automated tests.

Option 1: WordPress Playground

Playground runs a disposable WordPress in your browser with the pull request already applied.

1. Open the ticket on Core Trac and click View PR. This only works for a ticket with a GitHub pull request, not a .patch file.
2. In the pull request's comments, find Test using WordPress Playground and click Test this pull request with WordPress Playground.
3. Wait for Playground to prepare the site. If it doesn't redirect, click Go.

You can also build the address yourself. https://playground.wordpress.net/?wp=trunk&php=8.3&core-pr=12345 loads trunk on PHP 8.3 with pull request 12345 applied. Add &plugin=test-reports to install the Test Reports plugin too. See Test Core tickets with Playground for every option.

Option 2: WordPress Contributor Toolkit

The Contributor Toolkit is a desktop app for macOS (Apple Silicon), Windows and Linux. It downloads wordpress-develop, builds it and runs it for you, with no Git, Node.js, npm or Docker to install. It applies both pull requests and Trac .diff files, which makes it the easiest full setup for a first test.

1. Download it from the Releases page and open it.
2. Click Create a site, choose a folder and keep WordPress Core selected. The first build takes a while, so do this a day before a Contributor Day.
3. Click Start dev server. Your site opens in the browser; log in with admin and password.
4. Type the ticket number into the Trac ticket panel and click Link ticket. The panel lists the ticket's pull requests and, under Show Trac attachments, its patch files.
5. Click Apply… next to the pull request or patch you want to test, check the list of files it changes, then click Apply and rebuild.

When you're done, Revert this PR puts the site back the way it was. The Toolkit's site uses an SQLite database, so a ticket about MySQL-specific behaviour still needs Option 3.

Option 3: wordpress-develop with Docker

The classic setup gives you full control, and it's what you need to run PHPUnit and end-to-end tests. You'll need Git, Node.js with npm, and Docker.

git clone https://github.com/WordPress/wordpress-develop.git
cd wordpress-develop
npm install
npm run build:dev
npm run env:start
npm run env:install

Your site runs at http://localhost:8889. Log in with admin and password.

Apply a patch with grunt patch, by ticket number or by pull request:

# the patch attached to Trac ticket 12345
npm run grunt patch:12345

# or a pull request on wordpress-develop
npm run grunt patch:https://github.com/WordPress/wordpress-develop/pull/1234

If the patch changes JavaScript or CSS, run npm run build:dev again before testing.

If the patch fails to apply, update to the latest trunk and try again:

git checkout trunk
git pull upstream trunk

If Git says upstream doesn't exist, add it first with git remote add upstream https://github.com/WordPress/wordpress-develop.git. See Test Core tickets with grunt for more.

Pick a ticket

Start with the needs-testing queue on Core Trac. For a first test, choose something you can see in the browser, such as an admin screen, a block or a theme. Read the whole ticket, including the comments, so you know what the bug is and what the patch is meant to change.

Gutenberg has its own lists of issues and pull requests that need testing. Every Monday, the Test Team also posts a testing digest in #core-test.

Reproduce the bug first

Before applying anything, confirm the bug on a clean trunk. Follow the steps in the ticket and note what you see. If you can't reproduce it, that is useful too: say so with your environment details, using the Reproduction Report template.

Test and write your report

Repeat the steps from the ticket with the patch applied. Check the fix itself, then look around it for anything the change might have broken. Then post a report on the ticket using the Patch Testing Report template:

== Patch Testing Report

Patch tested: [link to the patch or pull request]

=== Environment
- WordPress: 7.2-alpha
- PHP: 8.3
- Server: nginx
- Database: MySQL 8.0
- Browser: Chrome
- OS: macOS
- Theme: Twenty Twenty-Five
- MU Plugins: None activated
- Plugins: None activated

=== Steps taken
1. Open Settings → General.
2. Change the site title and save.
3. ✅ Patch is solving the problem.

=== Expected result
- The new title shows in the admin bar right away.

=== Additional Notes
- No regressions found on the Settings screens.

=== Screenshots/Screencast with results
Before: [screenshot]
After: [screenshot]

The Test Reports plugin fills in the Environment section for you: install it, open Tools → Test Reports, choose Patch Testing and Trac, then add your steps and results. Before and after screenshots, or a short recording, make your report much easier to trust.

Reset for the next test

Start every test from a clean trunk:

• Playground: close the tab.
• Contributor Toolkit: click Revert this PR, or revert the applied patch.
• wordpress-develop: remove the patch with git checkout . and git clean -fd. These discard your local changes, so only run them in the checkout you use for testing.

Where to ask for help

Join #core-test on Make WordPress Slack. The Test Team meets there every Thursday at 15:00 UTC, with patch testing scrubs on the second and fourth Thursdays, and nobody minds a first-timer's question. If you're at a WordCamp, the Test table at Contributor Day is the fastest way to get your first report posted with someone beside you. See Planning to join the Test Team table at Contributor Day? for what to set up beforehand.