I’ve been focused on understanding deeply how unit tests work in WordPress for PHP code. One of the things that don’t come out of the box is direct access from the IDE to extended information of the methods and classed used in tests through Intellisense.
If you don’t do some extra setup your IDE has no idea where these classes like WP_UnitTestCase or functions like wp_insert_post, do_action really live. That means no IntelliSense, no “Go to Definition,” and no helpful type hints.
In this article I explaing how to get Cursor or Visual Code to know exactly where the WordPress test suite and core functions are—no matter what development setup you use.
I’ll use a Composer package + include paths approach because:
- It works on any type of local development environment: anywhere—Docker, Local, MAMP, XAMPP, custom LAMP/LEMP stacks, etc.
- It keeps IntelliSense working without touching your test runtime configuration
- It’s a good solution for team projects (automatically managed via Composer)
- Simpler setup than submodules with automatic version management
I’ll focus my explanations during the article on the wp-env local development environment but same approach can be used in other type of environments just by adjusting the paths required by Intellisense as covered later in the article.
Table of Contents
- The Problem
- Step-by-Step: Composer Package + Include Paths (Works Everywhere)
- Special Case: Using install-wp-tests.sh
- Special Case: Using wp-env
- Troubleshooting
- Conclusion
The Problem
WordPress’ PHPUnit framework lives in the Core repo under /tests/phpunit.
If you’re using wp-env or running tests in a container, those files aren’t on your local filesystem—your IDE can’t index them.
Even if you’re running WordPress locally, you may not have the Core test suite in your project folder unless you’ve installed it explicitly.
A good solution is to download the test suite for IntelliSense only (not for runtime) and point your IDE to it.
Step-by-Step: Composer Package + Include Paths (Works Everywhere)
1. Install the WordPress test suite via Composer
Use the official wp-phpunit/wp-phpunit package that mirrors the WordPress Core test suite:
composer require --dev wp-phpunit/wp-phpunitThis installs the WordPress test suite into vendor/wp-phpunit/wp-phpunit. The package contains all the testing framework classes and utilities that WordPress uses internally, including the base WP_UnitTestCase class that most WordPress plugin tests extend from.
💡 You can also use this package for bootstrapping your tests by requiring vendor/wp-phpunit/wp-phpunit/includes/bootstrap.php in your test bootstrap file.
2. Add WordPress Core for function IntelliSense
The easiest way: install WordPress Core as a dev dependency via Composer:
composer require --dev johnpbloch/wordpress-coreIf you already have a local copy of WordPress Core, you can point IntelliSense directly to that folder instead.
Alternative: Stubs-only (lighter)
If you want IntelliSense without pulling Core code:
composer require --dev php-stubs/wordpress-stubs php-stubs/wordpress-tests-stubsNote: Stubs provide function/class signatures and PHPDocs only. “Go to Definition” will open the stub files, not the real WordPress Core implementation. If you want to navigate into the actual Core sources, use the full Core approach below (e.g.,
composer require --dev johnpbloch/wordpress-core) and add its path to your include paths.
3. Configure Intelephense in VS Code
In .vscode/settings.json:
{
"intelephense.environment.includePaths": [
"vendor/wp-phpunit/wp-phpunit",
"vendor/johnpbloch/wordpress-core"
],
"intelephense.files.exclude": [
"tests/.stubs/**"
]
}For the stubs-only approach:
{
"intelephense.environment.includePaths": [
"vendor/php-stubs/wordpress-stubs",
"vendor/php-stubs/wordpress-tests-stubs"
]
}Then run: Cmd+Shift+P → “Developer: Reload Window”.
4. Updating the test suite later (if needed)
composer update wp-phpunit/wp-phpunitSpecial Case: Using install-wp-tests.sh
If you set up your test environment with the classic install-wp-tests.sh script, you can still benefit from the Composer approach for better dependency management.
The script typically downloads:
- Core test framework →
/tmp/wordpress-tests-lib - WordPress Core →
/tmp/wordpress
You can just point Intelephense to those paths:
{
"intelephense.environment.includePaths": [
"/tmp/wordpress-tests-lib",
"/tmp/wordpress"
],
"intelephense.files.exclude": [
"tests/.stubs/**"
]
}⚠️ Caveat:
/tmpcan be cleaned automatically, and these paths are machine-specific—so this approach is not team-friendly unless everyone uses the same setup.
If you installed WordPress in a custom location (e.g., MAMP’s htdocs), just replace /tmp/wordpress with the real path to your install.
Special Case: Using wp-env
If you’re using wp-env, you might have noticed that it generates a random hash as the container identifier, which results in paths like:
~/.wp-env/4fe04d64047d66ff68c5eeab343c6f85/WordPress
~/.wp-env/4fe04d64047d66ff68c5eeab343c6f85/WordPress-PHPUnit/tests/phpunitThese paths work fine for running tests, but they’re a pain to reference in your IntelliSense configuration—especially if you want to share settings across your team or automate anything.
Unfortunately, wp-env doesn’t provide a way to customize the directory name. The hash is generated automatically based on your project path using MD5.
However, you have a few practical alternatives:
Option 1: Use the Composer approach (recommended)
The most reliable solution is to use the Composer package approach described earlier in this article. This gives you stable, version-controlled paths regardless of your wp-env setup:
{
"intelephense.environment.includePaths": [
"vendor/wp-phpunit/wp-phpunit",
"vendor/johnpbloch/wordpress-core"
]
}Option 2: Find your wp-env path
You can find your current wp-env installation path using:
wp-env install-pathThis will output something like:
/Users/your-username/.wp-env/4fe04d64047d66ff68c5eeab343c6f85Then use this path in your IntelliSense configuration:
{
"intelephense.environment.includePaths": [
"/Users/your-username/.wp-env/4fe04d64047d66ff68c5eeab343c6f85/WordPress",
"/Users/your-username/.wp-env/4fe04d64047d66ff68c5eeab343c6f85/WordPress-PHPUnit/tests/phpunit"
]
}⚠️ Important: This path will change if you destroy and recreate your wp-env environment, so the Composer approach above is more stable for team environments.
Conclusion
This method provides a universal solution that adapts to any WordPress development environment:
- Docker environments: Enables IntelliSense access to containerized WordPress files
- Local setups (MAMP/XAMPP): Maintains stable paths under version control
- CI/CD pipelines: Offers development improvements without affecting runtime performance
The approach ensures consistent IDE support across different development workflows while keeping the implementation lightweight and environment-agnostic.
Leave a Reply