DocsWP — WordPress Help

Set Up a Testing Environment

To test WordPress core tickets effectively, you need an environment where you can apply patches and run tests. Patches are created against the trunk branch, the development version of WordPress, not the stable release from wordpress.org/download, so you’ll need to work with the development codebase. This guide covers the options available for setting up a testing environment.

Choose Your Environment

There are two main ways to test WordPress core tickets:

  1. WordPress Playground (Browser-based): Best for quick visual testing and verifying patches without installing anything on your computer.
  2. Local Development Environment: Required for more advanced testing, running automated tests (PHPUnit, e2e), and working with complex patches or build tools.

When to use Playground?

  • You need to quickly verify a visual change or a bug fix.
  • You cannot or do not want to install software on your computer.
  • The ticket has a Pull Request (PR) or a ZIP file that Playground can load.

Learn how to use Playground for testing

When to use a Local Environment?

  • You need to use command-line tools like grunt or git.
  • You want to run automated test suites (PHPUnit, end-to-end tests).
  • You are developing a patch or working on a complex feature that requires a persistent environment.

Setting Up a Local Environment

The recommended way to set up a local environment for WordPress core development is using Docker.

Prerequisites

Before you begin, ensure you have the following installed on your computer:
1. Node.js: Version 20.x or later.
2. npm: Version 10.x or later (usually comes with Node.js).
3. Git: For version control.
4. Docker Desktop (or a compatible container runtime like OrbStack, Colima, or Rancher Desktop).

Setup Instructions

Prefer a video walkthrough?
Follow along with this step-by-step setup guide as you work through the instructions below.

  1. Fork and Clone the Repository
    Fork the WordPress/wordpress-develop repository to your GitHub account, then clone it locally:

    git clone https://github.com/YOUR_USERNAME/wordpress-develop.git
cd wordpress-develop
git remote add upstream https://github.com/WordPress/wordpress-develop.git

    Adding the upstream remote allows you to keep your local repository in sync with the latest changes from WordPress core.

  2. Install Dependencies
    Run the following command to install the necessary JavaScript and PHP tools:

    npm install
  3. Build WordPress
    Compile the source files into a running WordPress instance:

    npm run build:dev
  4. Start the Environment
    Ensure Docker Desktop is running, then start the Docker environment:

    npm run env:start
  5. Install WordPress
    Run the installation script to set up the database and site:

    npm run env:install

Your local WordPress site should now be accessible at http://localhost:8889.

  • Username: admin
  • Password: password

Common Commands

  • Start environment: npm run env:start
  • Stop environment: npm run env:stop
  • Reset environment: npm run env:reset (Warning: deletes database)
  • Run WP-CLI commands: npm run env:cli -- <command> (e.g., npm run env:cli -- user list)

Next Steps

Now that your local environment is set up, learn how to apply patches and run tests:

Resources