[DOCS] Running PHPUnit tests using the Playground CLI (#3487)

## Motivation for the change, related issues

The Playground CLI's `php` subcommand makes it easy to run PHPUnit for
plugins and themes without a local database, but there's no guide
documenting this workflow.

## Implementation details

- Adds a new guide at
`packages/docs/site/docs/main/guides/phpunit-testing.md` covering:
  - Basic usage with `npx @wp-playground/cli@latest php`
  - Examples for both plugins and themes
  - Choosing PHP and WordPress versions
- Adds the guide to the sidebar in `sidebars.js` (between the
programmatic CLI guide and the E2E testing guide)
- Adds a link to the guide in the guides index page

## Testing Instructions

1. Run `npm run dev:docs`
2. Navigate to the Guides section
3. Confirm the "Running PHPUnit with the Playground CLI" guide appears
in the sidebar and index
4. Open the guide and verify all links work
5. Review the guide content and test it

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bgrgicak

packages/docs/site/docs/main/guides/index.md

@@ -45,6 +45,10 @@ Automate WordPress Playground workflows with Claude Code. Learn how to install t
 
 Learn how to use the `runCLI` function to control WordPress Playground programmatically from JavaScript/TypeScript for automation, end-to-end testing, and CI/CD pipelines.
 
+## [Running PHPUnit with the Playground CLI](/guides/phpunit-testing)
+
+Run PHPUnit tests for WordPress plugins and themes using the Playground CLI — no database required, clean environment on every run.
+
 ## [E2E Testing with Playwright and WordPress Playground](/guides/e2e-testing-with-playwright)
 
 Set up automated end-to-end tests for your WordPress plugins and themes using Playwright and the WordPress Playground CLI.

packages/docs/site/docs/main/guides/phpunit-testing.md

@@ -0,0 +1,67 @@
+---
+title: Running PHPUnit with the Playground CLI
+slug: /guides/phpunit-testing
+description: Run PHPUnit tests for WordPress plugins and themes using the Playground CLI — no database required, clean environment on every run.
+sidebar_class_name: navbar-build-item
+---
+
+The [Playground CLI](/developers/local-development/wp-playground-cli) includes a `php` subcommand that runs PHP scripts directly inside the Playground environment. By mounting your plugin or theme into the Playground filesystem, you can run PHPUnit without a local database. Every run starts with a clean WordPress installation, so tests are fully isolated.
+
+:::info
+This guide assumes your plugin or theme has PHPUnit installed via Composer (`composer require --dev phpunit/phpunit`). The `vendor/bin/phpunit` path used below assumes a standard Composer setup.
+:::
+
+## Running tests
+
+From your plugin or theme directory, run the following command. Replace `themes/THEME_NAME` with the path to your plugin or theme:
+
+```bash
+npx @wp-playground/cli@latest php \
+  --auto-mount \
+  -- \
+  /wordpress/wp-content/themes/THEME_NAME/vendor/bin/phpunit \
+  -c /wordpress/wp-content/themes/THEME_NAME/phpunit.xml.dist
+```
+
+The `--auto-mount` flag detects whether the current directory is a plugin, theme, or WordPress installation and mounts it at the correct path under `/wordpress/wp-content/`. The `--` separates CLI flags from arguments passed to the PHP interpreter, and you can pass any arguments supported by your PHPUnit configuration.
+
+For a plugin, the path would use `plugins/` instead:
+
+```bash
+npx @wp-playground/cli@latest php \
+  --auto-mount \
+  -- \
+  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
+  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
+```
+
+You can also use `--mount` to explicitly map a local directory to a path inside the Playground filesystem:
+
+```bash
+npx @wp-playground/cli@latest php \
+  --mount=.:/wordpress/wp-content/plugins/MY_PLUGIN \
+  -- \
+  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
+  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
+```
+
+## Choosing PHP and WordPress versions
+
+Use the `--php` and `--wp` flags to test against specific versions:
+
+```bash
+npx @wp-playground/cli@latest php \
+  --auto-mount \
+  --php=8.1 \
+  --wp=6.5 \
+  -- \
+  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
+  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
+```
+
+Supported PHP versions range from 7.4 to 8.5. For WordPress, you can use a specific version number, `latest`, `nightly`, or `beta`.
+
+## Next steps
+
+- [Playground CLI documentation](/developers/local-development/wp-playground-cli) — full CLI reference and configuration options
+- [E2E Testing with Playwright](/guides/e2e-testing-with-playwright) — browser-based end-to-end testing for WordPress plugins and themes

packages/docs/site/sidebars.js

@@ -53,6 +53,7 @@ const sidebars = {
 						'main/guides/github-action-pr-preview',
 						'main/guides/playground-for-everyone',
 						'main/guides/programmatic-playground-cli',
+						'main/guides/phpunit-testing',
 						'main/guides/e2e-testing-with-playwright',
 					],
 				},