From cc40738037aa2e8242f59f4f54c0a751294c2440 Mon Sep 17 00:00:00 2001
From: Hug0-Drelon <hugo.drelon@gmail.com>
Date: Wed, 14 Oct 2026 12:20:17 +0200
Subject: [PATCH 1/5] feat(config): add configurable WP-CLI command for wp-env
 11+

Add wpCliCommand option to getPlaywrightConfig, wpEnvRun helper, and
update createTranslator to use the shared command resolution.
---
 README.md            | 18 ++++++++++++++++
 src/config/index.js  | 15 +++++++++----
 src/config/wp-cli.js | 51 ++++++++++++++++++++++++++++++++++++++++++++
 src/index.js         |  1 +
 src/users/index.js   | 12 ++++-------
 5 files changed, 85 insertions(+), 12 deletions(-)
 create mode 100644 src/config/wp-cli.js

diff --git a/README.md b/README.md
index aefcb74..b860a8e 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,8 @@ import { getPlaywrightConfig } from '@wpsyntex/e2e-test-utils';
 export default getPlaywrightConfig( {
   globalSetup: './global.setup.mjs',
   globalTeardown: './global.teardown.mjs',
+  // Required with wp-env 11+ when using a separate test config file:
+  wpCliCommand: 'npx wp-env --config=.wp-env.test.json run cli',
 } );
 ```
 
@@ -52,6 +54,7 @@ The `getPlaywrightConfig` function accepts an options object that can override a
 
 - `use`: Override default Playwright use options
 - `webServer`: Override default webServer configuration
+- `wpCliCommand`: Base `wp-env run …` command for WP-CLI helpers such as `createTranslator`. Defaults to `npx wp-env run tests-cli`. Can also be set via the `WP_ENV_CLI_COMMAND` environment variable.
 - Any other Playwright configuration options
 
 #### Default Configuration
@@ -194,6 +197,21 @@ Reads a file and returns its contents as a string.
   - `filePath`: The file path to read
 - **Returns:** String content of the file
 
+#### 🔧 WP-CLI Utilities
+
+##### `wpEnvRun( command, shellPrefix = '' )`
+
+Runs a WP-CLI command in the wp-env test environment. Uses the command configured via `getPlaywrightConfig({ wpCliCommand })` or the `WP_ENV_CLI_COMMAND` environment variable.
+
+- **Parameters:**
+  - `command`: The WP-CLI command to run (e.g. `wp pll setting get`)
+  - `shellPrefix`: Optional shell prefix (e.g. `echo "y" |`)
+- **Returns:** The command output as a string
+
+##### `getWpCliCommand()`
+
+Returns the base `wp-env run …` command used by `wpEnvRun` and `createTranslator`. Configure it via `getPlaywrightConfig({ wpCliCommand })` or the `WP_ENV_CLI_COMMAND` environment variable.
+
 #### 🔧 Additional Exports
 
 ##### `globalSetup`
diff --git a/src/config/index.js b/src/config/index.js
index f263a89..7113e7d 100644
--- a/src/config/index.js
+++ b/src/config/index.js
@@ -1,5 +1,6 @@
 import { defineConfig, devices } from '@playwright/test';
 import path from 'path';
+import { setWpCliCommand } from './wp-cli.js';
 
 const STORAGE_STATE_PATH =
 	process.env.STORAGE_STATE_PATH ||
@@ -10,10 +11,16 @@ const STORAGE_STATE_PATH =
  *
  * @since 0.1.0
  *
- * @param {import('@playwright/test').PlaywrightTestConfig} options Options to merge with the default config.
+ * @param {import('@playwright/test').PlaywrightTestConfig & { wpCliCommand?: string }} options Options to merge with the default config.
  * @return {import('@playwright/test').PlaywrightTestConfig} Playwright config object.
  */
 export function getPlaywrightConfig( options = {} ) {
+	const { wpCliCommand, ...playwrightOptions } = options;
+
+	if ( wpCliCommand ) {
+		setWpCliCommand( wpCliCommand );
+	}
+
 	return defineConfig( {
 		testDir: './specs',
 		globalSetup: path.resolve( __dirname, '../setup/global.setup.cjs' ),
@@ -28,7 +35,7 @@ export function getPlaywrightConfig( options = {} ) {
 			trace: 'on-first-retry',
 			headless: true,
 			storageState: STORAGE_STATE_PATH,
-			...options.use,
+			...playwrightOptions.use,
 		},
 		projects: [
 			{
@@ -43,8 +50,8 @@ export function getPlaywrightConfig( options = {} ) {
 			reuseExistingServer: true,
 			cwd: process.cwd(),
 			timeout: 120 * 1000,
-			...options.webServer,
+			...playwrightOptions.webServer,
 		},
-		...options,
+		...playwrightOptions,
 	} );
 }
diff --git a/src/config/wp-cli.js b/src/config/wp-cli.js
new file mode 100644
index 0000000..5a2a525
--- /dev/null
+++ b/src/config/wp-cli.js
@@ -0,0 +1,51 @@
+import { execSync } from 'child_process';
+
+/** @type {string} */
+const DEFAULT_WP_CLI_COMMAND = 'npx wp-env run tests-cli';
+
+/**
+ * Returns the base `wp-env run …` command used to invoke WP-CLI.
+ *
+ * Resolution order:
+ * 1. `process.env.WP_ENV_CLI_COMMAND`
+ * 2. {@link DEFAULT_WP_CLI_COMMAND}
+ *
+ * @since 0.2.0
+ *
+ * @return {string} Base wp-env run command (without trailing WP-CLI arguments).
+ */
+export function getWpCliCommand() {
+	return process.env.WP_ENV_CLI_COMMAND || DEFAULT_WP_CLI_COMMAND;
+}
+
+/**
+ * Sets the base `wp-env run …` command for utility functions such as `createTranslator`.
+ *
+ * @since 0.2.0
+ *
+ * @param {string} command Base wp-env run command (without trailing WP-CLI arguments).
+ */
+export function setWpCliCommand( command ) {
+	process.env.WP_ENV_CLI_COMMAND = command;
+}
+
+/**
+ * Runs a WP-CLI command in the wp-env test environment.
+ *
+ * @since 0.2.0
+ *
+ * @param {string} command     The WP-CLI command to run (e.g. `wp pll setting get`).
+ * @param {string} shellPrefix Optional shell prefix (e.g. `echo "y" |`).
+ * @return {string} The command output.
+ */
+export function wpEnvRun( command, shellPrefix = '' ) {
+	const cliCommand = `${ getWpCliCommand() } ${ command }`;
+	const fullCommand = shellPrefix
+		? `${ shellPrefix } ${ cliCommand }`
+		: cliCommand;
+
+	return execSync( fullCommand, {
+		encoding: 'utf8',
+		stdio: 'pipe',
+	} );
+}
diff --git a/src/index.js b/src/index.js
index 6cb29d8..dc09b6f 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,4 +1,5 @@
 export { getPlaywrightConfig } from './config/index.js';
+export { getWpCliCommand, wpEnvRun } from './config/wp-cli.js';
 export { default as globalSetup } from './setup/global.setup.js';
 export {
 	getAllLanguages,
diff --git a/src/users/index.js b/src/users/index.js
index 8d99e4e..9d91db5 100644
--- a/src/users/index.js
+++ b/src/users/index.js
@@ -1,5 +1,5 @@
 // @ts-check
-import { execSync } from 'child_process';
+import { wpEnvRun } from '../config/wp-cli.js';
 
 /**
  * @typedef {import('@playwright/test').Page} Page
@@ -25,18 +25,14 @@ export async function createTranslator( langSlugs, userName = '' ) {
 			: userName;
 	const email = `${ userName.toLowerCase() }@example.com`;
 	const userId = parseInt(
-		execSync(
-			`npx wp-env run tests-cli wp user create ${ userName } ${ email } --role=editor --user_pass=password --porcelain`,
-			{ encoding: 'utf8' }
+		wpEnvRun(
+			`wp user create ${ userName } ${ email } --role=editor --user_pass=password --porcelain`
 		).trim(),
 		10
 	);
 
 	langSlugs.forEach( ( langSlug ) => {
-		execSync(
-			`npx wp-env run tests-cli wp user add-cap ${ userId } translate_${ langSlug }`,
-			{ encoding: 'utf8' }
-		);
+		wpEnvRun( `wp user add-cap ${ userId } translate_${ langSlug }` );
 	} );
 
 	return { id: userId, username: userName, password: 'password' };

From 709fc009925d0e7e22bcd4c541c3d0fc8a265c4f Mon Sep 17 00:00:00 2001
From: Hug0-Drelon <hugo.drelon@gmail.com>
Date: Wed, 14 Oct 2026 19:03:34 +0200
Subject: [PATCH 2/5] fix(config): prevent playwrightOptions from overwriting
 use and webServer

Destructure use and webServer out of options before spreading
playwrightOptions so merged defaults are not replaced wholesale.
---
 src/config/index.js | 22 +++++++++-------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/src/config/index.js b/src/config/index.js
index 7113e7d..5bce75b 100644
--- a/src/config/index.js
+++ b/src/config/index.js
@@ -6,16 +6,13 @@ const STORAGE_STATE_PATH =
 	process.env.STORAGE_STATE_PATH ||
 	path.join( process.cwd(), 'artifacts/storage-states/admin.json' );
 
-/**
- * Returns a Playwright config object.
- *
- * @since 0.1.0
- *
- * @param {import('@playwright/test').PlaywrightTestConfig & { wpCliCommand?: string }} options Options to merge with the default config.
- * @return {import('@playwright/test').PlaywrightTestConfig} Playwright config object.
- */
 export function getPlaywrightConfig( options = {} ) {
-	const { wpCliCommand, ...playwrightOptions } = options;
+	const {
+		wpCliCommand,
+		use: useOptions = {},
+		webServer: webServerOptions = {},
+		...playwrightOptions
+	} = options;
 
 	if ( wpCliCommand ) {
 		setWpCliCommand( wpCliCommand );
@@ -35,7 +32,7 @@ export function getPlaywrightConfig( options = {} ) {
 			trace: 'on-first-retry',
 			headless: true,
 			storageState: STORAGE_STATE_PATH,
-			...playwrightOptions.use,
+			...useOptions,
 		},
 		projects: [
 			{
@@ -44,13 +41,12 @@ export function getPlaywrightConfig( options = {} ) {
 			},
 		],
 		webServer: {
-			// wp-env start exits after containers are up; keep the process alive so Playwright can wait for a 2xx response.
-			command: 'npm run env:start && sleep 86400', // 24 hours.
+			command: "npm run env:start && sleep 86400",
 			url: 'http://localhost:8889',
 			reuseExistingServer: true,
 			cwd: process.cwd(),
 			timeout: 120 * 1000,
-			...playwrightOptions.webServer,
+			...webServerOptions,
 		},
 		...playwrightOptions,
 	} );

From 13b80b52d72531e156eb354572131b111b6b4266 Mon Sep 17 00:00:00 2001
From: Hug0-Drelon <hugo.drelon@gmail.com>
Date: Thu, 15 Oct 2026 15:34:01 +0200
Subject: [PATCH 3/5] fix(eslint) format config/index.js

---
 src/config/index.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/config/index.js b/src/config/index.js
index 5bce75b..222fd76 100644
--- a/src/config/index.js
+++ b/src/config/index.js
@@ -41,7 +41,7 @@ export function getPlaywrightConfig( options = {} ) {
 			},
 		],
 		webServer: {
-			command: "npm run env:start && sleep 86400",
+			command: 'npm run env:start && sleep 86400',
 			url: 'http://localhost:8889',
 			reuseExistingServer: true,
 			cwd: process.cwd(),

From 5d2e6f8c0358967ce6b60a749dc854facb02f4c8 Mon Sep 17 00:00:00 2001
From: Hug0-Drelon <hugo.drelon@gmail.com>
Date: Thu, 15 Oct 2026 15:38:13 +0200
Subject: [PATCH 4/5] refactor(wp-cli): rename wpEnvRun to runWpCli

Aligns with getWpCliCommand/setWpCliCommand and verb-first naming.
---
 README.md            | 4 ++--
 src/config/wp-cli.js | 2 +-
 src/index.js         | 2 +-
 src/users/index.js   | 6 +++---
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index b860a8e..a08171c 100644
--- a/README.md
+++ b/README.md
@@ -199,7 +199,7 @@ Reads a file and returns its contents as a string.
 
 #### 🔧 WP-CLI Utilities
 
-##### `wpEnvRun( command, shellPrefix = '' )`
+##### `runWpCli( command, shellPrefix = '' )`
 
 Runs a WP-CLI command in the wp-env test environment. Uses the command configured via `getPlaywrightConfig({ wpCliCommand })` or the `WP_ENV_CLI_COMMAND` environment variable.
 
@@ -210,7 +210,7 @@ Runs a WP-CLI command in the wp-env test environment. Uses the command configure
 
 ##### `getWpCliCommand()`
 
-Returns the base `wp-env run …` command used by `wpEnvRun` and `createTranslator`. Configure it via `getPlaywrightConfig({ wpCliCommand })` or the `WP_ENV_CLI_COMMAND` environment variable.
+Returns the base `wp-env run …` command used by `runWpCli` and `createTranslator`. Configure it via `getPlaywrightConfig({ wpCliCommand })` or the `WP_ENV_CLI_COMMAND` environment variable.
 
 #### 🔧 Additional Exports
 
diff --git a/src/config/wp-cli.js b/src/config/wp-cli.js
index 5a2a525..d6c8a1d 100644
--- a/src/config/wp-cli.js
+++ b/src/config/wp-cli.js
@@ -38,7 +38,7 @@ export function setWpCliCommand( command ) {
  * @param {string} shellPrefix Optional shell prefix (e.g. `echo "y" |`).
  * @return {string} The command output.
  */
-export function wpEnvRun( command, shellPrefix = '' ) {
+export function runWpCli( command, shellPrefix = '' ) {
 	const cliCommand = `${ getWpCliCommand() } ${ command }`;
 	const fullCommand = shellPrefix
 		? `${ shellPrefix } ${ cliCommand }`
diff --git a/src/index.js b/src/index.js
index dc09b6f..277d05f 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,5 +1,5 @@
 export { getPlaywrightConfig } from './config/index.js';
-export { getWpCliCommand, wpEnvRun } from './config/wp-cli.js';
+export { getWpCliCommand, runWpCli } from './config/wp-cli.js';
 export { default as globalSetup } from './setup/global.setup.js';
 export {
 	getAllLanguages,
diff --git a/src/users/index.js b/src/users/index.js
index 9d91db5..b3b072c 100644
--- a/src/users/index.js
+++ b/src/users/index.js
@@ -1,5 +1,5 @@
 // @ts-check
-import { wpEnvRun } from '../config/wp-cli.js';
+import { runWpCli } from '../config/wp-cli.js';
 
 /**
  * @typedef {import('@playwright/test').Page} Page
@@ -25,14 +25,14 @@ export async function createTranslator( langSlugs, userName = '' ) {
 			: userName;
 	const email = `${ userName.toLowerCase() }@example.com`;
 	const userId = parseInt(
-		wpEnvRun(
+		runWpCli(
 			`wp user create ${ userName } ${ email } --role=editor --user_pass=password --porcelain`
 		).trim(),
 		10
 	);
 
 	langSlugs.forEach( ( langSlug ) => {
-		wpEnvRun( `wp user add-cap ${ userId } translate_${ langSlug }` );
+		runWpCli( `wp user add-cap ${ userId } translate_${ langSlug }` );
 	} );
 
 	return { id: userId, username: userName, password: 'password' };

From ee37a8da048a6b6954fd78dea9ec748ba23c789c Mon Sep 17 00:00:00 2001
From: Hug0-Drelon <hugo.drelon@gmail.com>
Date: Thu, 15 Oct 2026 15:58:55 +0200
Subject: [PATCH 5/5] docs(config): restore webServer sleep comment

---
 src/config/index.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/config/index.js b/src/config/index.js
index 222fd76..60086ad 100644
--- a/src/config/index.js
+++ b/src/config/index.js
@@ -41,7 +41,8 @@ export function getPlaywrightConfig( options = {} ) {
 			},
 		],
 		webServer: {
-			command: 'npm run env:start && sleep 86400',
+			// wp-env start exits after containers are up; keep the process alive so Playwright can wait for a 2xx response.
+			command: 'npm run env:start && sleep 86400', // 24 hours.
 			url: 'http://localhost:8889',
 			reuseExistingServer: true,
 			cwd: process.cwd(),