Local WordPress Core Testing Setup Guide

This guide walks you through setting up a local WordPress development environment specifically for core testing—whether you’re testing patches, reproducing bugs, or contributing to WordPress core. You’ll end up with a fast, isolated WordPress installation where you can safely experiment without affecting any live site. Before you begin, make sure you have a code editor and a basic understanding of the command line.

What You’ll Need

• A computer running Windows, macOS, or Linux
• Local development software (like Local, XAMPP, MAMP, or Docker)
• A code editor (VS Code, Sublime Text, etc.)
• Git installed on your machine
• Node.js and npm (for building WordPress assets if needed)
• A web browser

Step-by-Step

1. Install local development software. Choose one tool that fits your workflow. For beginners, Local (by Flywheel) is user-friendly and handles most setup automatically. For more advanced users, Docker with a WordPress image offers greater control. Download and install your chosen software, then launch it.
2. Create a new local site. In your local development tool, create a new WordPress site. Name it something like “wordpress-core-test” and set the environment to PHP 8.0 or later (as of WordPress 6.x, PHP 7.4+ is recommended, but 8.x is best for testing current core). Choose a web server (Apache or Nginx) and a database type (MySQL or MariaDB). The tool will create a fresh WordPress installation for you.
3. Install Git if you haven’t. Git is essential for cloning the WordPress core repository. On Windows, download Git for Windows. On macOS, install via Homebrew (brew install git). On Linux, use your package manager (e.g., sudo apt install git). Verify installation with git --version.
4. Clone the WordPress core repository. Open a terminal in your site’s root directory (the folder where WordPress files are located). If you used Local, you can find the path by right-clicking your site and selecting “Show Folder”. Then run: git clone https://github.com/WordPress/wordpress-develop.git . This downloads the full development repository, which includes the src folder (the actual WordPress code) and tests folder (automated tests).
5. Replace your site’s files with the repository files. After cloning, you’ll have a wordpress-develop folder inside your site directory. Move its contents up to the site root, or point your local server to the wordpress-develop folder directly. For Local, you can change the site’s document root to that folder. Make sure to delete any default WordPress files that came with the initial installation to avoid conflicts.
6. Set up the database. WordPress core development uses a separate database for tests. Create a new database in your local tool (e.g., wordpress_core_test). Then, copy wp-config-sample.php to wp-config.php and edit it with your database credentials. For core testing, you also need to define WP_DEBUG as true and set the WP_TESTS_DOMAIN constant to your local site URL (e.g., wordpress-core-test.local).
7. Run the installation script. Open your browser and go to your local site URL (e.g., http://wordpress-core-test.local). Follow the WordPress installation wizard. Use a simple admin username and password (e.g., admin/admin). This creates the necessary tables in your main database.
8. Install test dependencies. Core testing requires PHPUnit and a few other tools. In your terminal, navigate to the wordpress-develop folder and run composer install (if you have Composer) or npm install to install JavaScript dependencies. These are needed for running the automated test suite.
9. Configure the test suite. Copy wp-tests-config-sample.php to wp-tests-config.php and edit it. Set DB_NAME to your test database name, DB_USER and DB_PASSWORD to your local database credentials, and WP_TESTS_DOMAIN to your local site URL. Also set WP_TESTS_EMAIL to a valid email address (any will do).
10. Test your setup. To verify everything works, run a basic test from the terminal: phpunit in the wordpress-develop folder. You should see a series of tests pass. If you get errors, check the troubleshooting section below.
11. Start testing core. You can now create branches, apply patches, and run tests. To test a specific patch, use git apply patch.diff or git apply --check to check first. After applying, run the relevant tests to see if they pass.

Common Mistakes

• Using the wrong folder. Cloning the repository into a subfolder and not pointing your server to the right root is a frequent error. Ensure your site’s document root is the folder containing wp-load.php (the root of the cloned repo).
• Not creating a separate test database. The test suite will drop tables in the database defined in wp-tests-config.php. If you use your main site’s database, you’ll lose all your data.
• Ignoring PHP version requirements. WordPress core requires PHP 7.4+ for testing, but some features need 8.0+. Check the readme.html in the repo for current requirements.
• Skipping Composer/npm install. Without these, PHPUnit and other tools won’t be available, and tests will fail with missing class errors.
• Editing files directly in the repository. Always use Git branches and patches. Editing directly makes it hard to track changes and revert.

Tips

• Use a version control workflow. Create a new branch for each issue you’re testing: git checkout -b test-12345. This keeps your main branch clean.
• Learn the test structure. WordPress tests are organized by component (e.g., tests/phpunit/tests/post). Run a specific test file with phpunit --filter test_name to save time.
• Use the built-in WP-CLI. The development repository includes bin/wp which is a wrapper for WP-CLI. You can use it to generate test content, manage options, etc.
• Keep your fork updated. Regularly pull the latest changes from the main WordPress repository to stay current: git fetch upstream and git merge upstream/master.
• Enable debugging. Set WP_DEBUG to true and WP_DEBUG_LOG to true in wp-config.php to see PHP errors in a log file.

Troubleshooting

• “Error establishing a database connection” — Check your wp-config.php credentials. Ensure the database exists and the user has privileges. If using Local, the host is often localhost and port 3306.
• PHPUnit not found — Run composer install in the repo root. If Composer isn’t installed, download it from getcomposer.org. Alternatively, install PHPUnit globally via composer global require phpunit/phpunit.
• Tests fail with “Table not found” — The test database isn’t set up correctly. Double-check wp-tests-config.php and ensure the test database exists. You can also run phpunit --install to force installation.
• Site shows 404 for all pages — This often happens when the permalink structure is wrong. Go to Settings > Permalinks in the admin and click “Save Changes” to flush rewrite rules. If that fails, check your local server’s mod_rewrite (Apache) or try switching to the “Plain” permalink structure.
• Git clone fails due to permissions — On macOS/Linux, ensure you have write permissions to the site folder. Use chmod -R u+w folder if needed. On Windows, run your terminal as Administrator.
• JavaScript errors in the admin — Run npm install and then npm run build to compile the admin assets. This is required for the block editor to work correctly.

Frequently Asked Questions

Do I need to use the same database for testing and my site?

No, you should always use a separate database for the test suite. The tests will wipe data, so using your main database will destroy your content.

Can I use any local server tool?

Yes, as long as it supports PHP 7.4+ and MySQL/MariaDB. Local, XAMPP, MAMP, and Docker all work. The key is to point the document root to the cloned repository.

How do I apply a patch from a ticket?

Download the patch file, then in your terminal run git apply /path/to/patch.diff. If it applies cleanly, you can test. If not, you may need to rebase or manually merge.

What is the difference between wordpress-develop and wordpress?

The wordpress-develop repository contains the full development environment, including tests, build scripts, and the source code in src. The regular wordpress repo is just the final production code.

Do I need to run the full test suite every time?

No, you can run specific tests. For example, phpunit --filter test_get_the_title runs only tests with that name. This speeds up development significantly.

How do I update my local environment to the latest WordPress core?

In the repo root, run git fetch upstream then git merge upstream/master. Then run composer install and npm install again to update dependencies.

Related

• Remove Uninstall Do Searches Hijacker?
• Which iPads Can Run iPadOS 16? Full List
• Printer Copies Setting: How to Print a Document Twice