From 2e26c858f75653a1d4b38edad6ab1bdf03b825cd Mon Sep 17 00:00:00 2001
From: Joe McGill <joe.mcgill@10up.com>
Date: Fri, 23 Feb 2024 10:25:58 -0600
Subject: [PATCH] Add instructions for running PHPUnit with wp-env.

This updates the README with the setup instructions for running PHPUnit tests with `wp-env`. This also adds a new `test:php` script to the `package.json` file to simplify running the tests locally.
---
 README.md    | 31 +++++++++++++++++++++++++++++++
 package.json |  3 ++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 432bc1f8c6..dc0bff4b1e 100644
--- a/README.md
+++ b/README.md
@@ -136,6 +136,37 @@ $ vendor/bin/phpunit
 
 The tests will execute and you'll be presented with a summary.
 
+### Running tests using `wp-env`
+
+To run PHPUnit from within the included `wp-env` environment, you will need to load the development version of the WooCommerce plugin in your environment.
+
+First, clone the WooCommerce repo, replacing `${WC_VERSION}` with the latest version of the plugin (e.g. 8.6.1):
+
+```bash
+$ git clone --depth=1 --branch="${WC_VERSION}" https://github.com/woocommerce/woocommerce.git ../woocommerce/`
+```
+
+Build the woocommerce plugin (see [this document](DEVELOPMENT.md) for additional instructions): 
+ - Go to the plugin directory: `cd ../woocommerce/plugins/woocommerce/`
+ - Install dependencies: `pnpm install`
+ - Build the plugin: `pnpm --filter=@woocommerce/plugin-woocommerce build`
+
+Go back to the Google Listings and Ads directory and create a `.wp-env.override.json` file containing the following:
+```json
+{
+	"plugins": [
+		"../woocommerce/plugins/woocommerce",
+		"."
+	]
+}
+```
+
+Restart your wp-env environment: `npm run wp-env start`
+
+You should now be able to run unit tests locally via the CLI: `npm run test:php`.
+
+To pass additional arguments to PHPUnit, make sure they are preceded by an additional `--`, like `npm run test:php -- --filter my_test_method`.
+
 ## E2E Testing
 
 E2E testing uses [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) which requires [Docker](https://www.docker.com/).
diff --git a/package.json b/package.json
index 76211df4b8..f1ab6d7eca 100644
--- a/package.json
+++ b/package.json
@@ -114,6 +114,7 @@
 		"test:e2e-dev": "npx playwright test --config=tests/e2e/config/playwright.config.js --debug",
 		"test:js": "wp-scripts test-unit-js --coverage",
 		"test:js:watch": "npm run test:js -- --watch",
+		"test:php": "wp-env run tests-wordpress --env-cwd=./wp-content/plugins/$(basename $(pwd)) ./vendor/bin/phpunit",
 		"test-proxy": "node ./tests/proxy",
 		"wp-env": "wp-env",
 		"wp-env:up": "npm run -- wp-env start --update",
@@ -171,4 +172,4 @@
 		"node": "^16 || ^18",
 		"npm": "^8 || ^9"
 	}
-}
+}
\ No newline at end of file