Commit 22e45e60c28 for woocommerce

commit 22e45e60c2814f3bc100b3ef43f0fcac69eec341
Author: Ján Mikláš <neosinner@gmail.com>
Date:   Wed Nov 18 18:33:33 2026 +0100

    Share Playwright site setup for Woo extensions (#71098)

    * feat: share extension Playwright site setup

    * chore: record shared Playwright site setup

    * fix: support both stable WooCommerce ZIP mounts

    * fix: validate extension browser site inputs

    * fix: validate wp-env PHP versions separately

    * fix: reject invalid browser test mounts

    * fix: validate browser test mount sources

    * fix: validate browser test site overrides

diff --git a/packages/js/extension-tooling/README.md b/packages/js/extension-tooling/README.md
index 315af5c7853..f52f06606ba 100644
--- a/packages/js/extension-tooling/README.md
+++ b/packages/js/extension-tooling/README.md
@@ -32,6 +32,20 @@ Choose a single folder name for `config.woo.zip.root`. When `build-zip` receives

 `e2e setup` uses the extension's `build:zip` script unless `E2E_PLUGIN_ZIP` supplies a ZIP. It calls `bin/link_plugins.js` to write `.wp-env.e2e.json`, `wp-env:e2e` to manage the site, and `env:test:e2e:seed` to seed it. `e2e with-env` also calls `test:e2e` to run the suite.

+In `bin/link_plugins.js`, call the shared site setup after any local preparation hook has gathered its fixtures.
+
+```js
+const path = require( 'node:path' );
+const writeE2ESiteConfig = require( '@woocommerce/extension-tooling/e2e-site-config' );
+
+writeE2ESiteConfig( {
+	root: path.resolve( __dirname, '..' ),
+	pluginPath: './deploy/e2e-plugin/your-extension',
+} );
+```
+
+The helper reads `.wp-env.test.json`, mounts the unpacked ZIP in place of `.` and maps a separate debug log. It applies the E2E runner's `WP_VERSION` and `WC_VERSION`. Set `E2E_PHP_VERSION` to a major and minor version such as `8.4` to override the browser site's PHP version. The debug log mount is set after `configure( config )`. WooCommerce overrides replace the `woocommerce.latest-stable.zip` or `woocommerce.zip` entry from `downloads.wordpress.org`. Use `configure( config )` to add local plugins or mappings, and pass `woocommerce.latest` or `woocommerce.nightly` when an integration requires a specific WooCommerce mount.
+
 `phpcs-baseline` uses the scan paths set by the extension's PHPCS ruleset. Declare at least one `<file>` entry in the ruleset.

 For hosts with Composer and no Node.js, check out this package's `bin` directory from a reviewed WooCommerce commit and run its Bash files directly. Install the tools used by the selected command, such as `jq` for configuration, `rsync` and `zip` for packaging, `unzip` for ZIP checks, `git` for syntax checks, and WP-CLI for POT generation. Keep `woo-config.sh` and `woo-config.schema.json` alongside the commands that read extension configuration. For example, from the extension root:
diff --git a/packages/js/extension-tooling/bin/e2e.sh b/packages/js/extension-tooling/bin/e2e.sh
index 51b5b55c22f..500349f8508 100644
--- a/packages/js/extension-tooling/bin/e2e.sh
+++ b/packages/js/extension-tooling/bin/e2e.sh
@@ -29,6 +29,7 @@ usage() {
 	Environment:
 	  E2E_PLUGIN_ZIP=<zip>          Test this ZIP instead of building deploy/<name>.zip
 	  E2E_WP_VERSION, E2E_WC_VERSION  latest (default), nightly or a release tag
+	  E2E_PHP_VERSION=X.Y        Select the browser site PHP image
 	  E2E_TARGET=<file>             Spec files to run: a path or part of a file name (run only)
 	  E2E_FILTER=<regex>            Test titles or tags to run, as --grep (run only)
 	  E2E_SHOW_UI=1                 Show the browser, as --headed (run only)
@@ -37,6 +38,11 @@ usage() {
 }

 prepare() {
+	if [[ -n "${E2E_PHP_VERSION+x}" && ! "${E2E_PHP_VERSION:-}" =~ ^[0-9]+\.[0-9]+$ ]]; then
+		echo "Invalid E2E_PHP_VERSION (expected major.minor)." >&2
+		exit 1
+	fi
+
 	local zip=${E2E_PLUGIN_ZIP:-}
 	if [[ -z "$zip" ]]; then
 		pnpm run build:zip
diff --git a/packages/js/extension-tooling/changelog/wooprd-4117-extract-shared-playwright-site-configuration b/packages/js/extension-tooling/changelog/wooprd-4117-extract-shared-playwright-site-configuration
new file mode 100644
index 00000000000..3dfe956c973
--- /dev/null
+++ b/packages/js/extension-tooling/changelog/wooprd-4117-extract-shared-playwright-site-configuration
@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Add a shared Playwright site configuration helper for WooCommerce extensions.
diff --git a/packages/js/extension-tooling/package.json b/packages/js/extension-tooling/package.json
index 5b20a55d28a..f0fb9e6b5a2 100644
--- a/packages/js/extension-tooling/package.json
+++ b/packages/js/extension-tooling/package.json
@@ -17,6 +17,7 @@
 		"./webpack-dist-minify": "./src/webpack-dist-minify.js",
 		"./webpack-text-includes": "./src/webpack-text-includes.js",
 		"./check-i18n": "./src/check-i18n.js",
+		"./e2e-site-config": "./src/e2e-site-config.js",
 		"./stylelint/legacy-scss": "./configs/stylelint-legacy-scss.json"
 	},
 	"bin": {
diff --git a/packages/js/extension-tooling/src/e2e-site-config.js b/packages/js/extension-tooling/src/e2e-site-config.js
new file mode 100644
index 00000000000..6f9ac60bb95
--- /dev/null
+++ b/packages/js/extension-tooling/src/e2e-site-config.js
@@ -0,0 +1,152 @@
+const fs = require( 'node:fs' );
+const path = require( 'node:path' );
+
+const latestWooCommerce =
+	'https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip';
+const stableWooCommerce =
+	'https://downloads.wordpress.org/plugin/woocommerce.zip';
+const nightlyWooCommerce =
+	'https://github.com/woocommerce/woocommerce/releases/download/nightly/woocommerce-trunk-nightly.zip';
+// Match dotted version numbers and pre-release tags such as 11.3.0-rc.1.
+const isVersionNumber = ( value ) =>
+	typeof value === 'string' && /^\d+(\.\d+)*(-\w+(\.\w+)*)*$/.test( value );
+const isMountSource = ( source ) =>
+	typeof source === 'string' && source.trim() !== '';
+
+function assertPluginSources( plugins, filename ) {
+	if (
+		! Array.isArray( plugins ) ||
+		plugins.findIndex( ( source ) => ! isMountSource( source ) ) !== -1
+	) {
+		throw new Error(
+			`${ filename } plugins must be an array of non-empty strings.`
+		);
+	}
+}
+
+function assertMappings( mappings, filename ) {
+	if (
+		! mappings ||
+		typeof mappings !== 'object' ||
+		Array.isArray( mappings ) ||
+		! Object.values( mappings ).every( isMountSource )
+	) {
+		throw new Error(
+			`${ filename } mappings must be an object of non-empty strings.`
+		);
+	}
+}
+
+function setSiteVersion( config, option, value ) {
+	config[ option ] = value;
+	const development = config.env?.development;
+	if ( development && Object.hasOwn( development, option ) ) {
+		development[ option ] = value;
+	}
+}
+
+/**
+ * Generate the browser test site config from the repo's wp-env tests site.
+ *
+ * @param {Object}   options                   Site setup options.
+ * @param {string}   options.root              Extension checkout directory.
+ * @param {string}   options.pluginPath        Relative path to the unpacked production plugin.
+ * @param {Object}   [options.env=process.env] WordPress, WooCommerce and explicit E2E PHP version variables.
+ * @param {Object}   [options.woocommerce]     Optional latest and nightly WooCommerce install sources.
+ * @param {Function} [options.configure]       Set repo-specific plugins and mappings.
+ */
+function writeE2ESiteConfig( {
+	root,
+	pluginPath,
+	env = process.env,
+	woocommerce = {},
+	configure,
+} ) {
+	const config = JSON.parse(
+		fs.readFileSync( path.join( root, '.wp-env.test.json' ), 'utf8' )
+	);
+	assertPluginSources( config.plugins, '.wp-env.test.json' );
+	const checkout = config.plugins.indexOf( '.' );
+	if ( checkout === -1 ) {
+		throw new Error( '.wp-env.test.json must mount the checkout as ".".' );
+	}
+	config.plugins[ checkout ] = pluginPath;
+	config.mappings ??= {};
+	assertMappings( config.mappings, '.wp-env.test.json' );
+	configure?.( config );
+
+	const { WC_VERSION = '', WP_VERSION, E2E_PHP_VERSION } = env;
+	let wooSource = woocommerce.latest ?? null;
+	if ( WC_VERSION === 'nightly' || WC_VERSION === 'trunk' ) {
+		wooSource = woocommerce.nightly ?? nightlyWooCommerce;
+	} else if ( WC_VERSION !== '' && WC_VERSION !== 'latest' ) {
+		if (
+			typeof WC_VERSION !== 'string' ||
+			! /^\d+\.\d+\.\d+(?:-[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*)?$/.test(
+				WC_VERSION
+			)
+		) {
+			throw new Error(
+				`Invalid WC_VERSION: ${ WC_VERSION } (expected latest, nightly or a release tag).`
+			);
+		}
+		wooSource =
+			'https://github.com/woocommerce/woocommerce/releases/download/' +
+			WC_VERSION +
+			'/woocommerce.zip';
+	}
+	if ( wooSource !== null && Array.isArray( config.plugins ) ) {
+		const wooIndex = config.plugins.findIndex(
+			( source ) =>
+				source === latestWooCommerce || source === stableWooCommerce
+		);
+		if ( wooIndex === -1 ) {
+			throw new Error(
+				'.wp-env.test.json must include a WooCommerce ZIP mount.'
+			);
+		}
+		config.plugins[ wooIndex ] = wooSource;
+	}
+
+	if ( WP_VERSION === 'nightly' ) {
+		setSiteVersion(
+			config,
+			'core',
+			'https://wordpress.org/nightly-builds/wordpress-latest.zip'
+		);
+	} else if ( isVersionNumber( WP_VERSION ) ) {
+		setSiteVersion(
+			config,
+			'core',
+			'https://wordpress.org/wordpress-' + WP_VERSION + '.zip'
+		);
+	}
+	if ( E2E_PHP_VERSION !== undefined ) {
+		if (
+			typeof E2E_PHP_VERSION !== 'string' ||
+			! /^\d+\.\d+$/.test( E2E_PHP_VERSION )
+		) {
+			throw new Error(
+				'Invalid E2E_PHP_VERSION (expected major.minor).'
+			);
+		}
+		setSiteVersion( config, 'phpVersion', E2E_PHP_VERSION );
+	}
+
+	assertPluginSources( config.plugins, '.wp-env.e2e.json' );
+	assertMappings( config.mappings, '.wp-env.e2e.json' );
+
+	const debugLog = 'wp-content/debug.log';
+	const debugLogMount = `./${ debugLog }`;
+	const developmentMappings = config.env?.development?.mappings;
+	delete config.mappings[ debugLog ];
+	delete developmentMappings?.[ debugLog ];
+	delete developmentMappings?.[ debugLogMount ];
+	config.mappings[ debugLogMount ] = './tests/_output/e2e-debug.log';
+	fs.writeFileSync(
+		path.join( root, '.wp-env.e2e.json' ),
+		JSON.stringify( config )
+	);
+}
+
+module.exports = writeE2ESiteConfig;
diff --git a/packages/js/extension-tooling/test/commands.test.js b/packages/js/extension-tooling/test/commands.test.js
index 8c00082499f..ce4a9f6179c 100644
--- a/packages/js/extension-tooling/test/commands.test.js
+++ b/packages/js/extension-tooling/test/commands.test.js
@@ -51,7 +51,7 @@ test( 'builds the plugin ZIP without npm and prepares that ZIP through a linked
 	);
 	fs.writeFileSync(
 		path.join( directory, 'bin/hooks/e2e-prepare.sh' ),
-		'printf "%s/%s" "$WP_VERSION" "$WC_VERSION" > deploy/versions\n'
+		'printf "%s/%s/%s" "$WP_VERSION" "$WC_VERSION" "$E2E_PHP_VERSION" > deploy/versions\n'
 	);
 	fs.writeFileSync(
 		path.join( directory, 'bin/link_plugins.js' ),
@@ -69,14 +69,25 @@ test( 'builds the plugin ZIP without npm and prepares that ZIP through a linked

 	const link = path.join( directory, 'woo-extension-tooling' );
 	fs.symlinkSync( path.join( toolingBin, 'woo-extension-tooling.js' ), link );
+	const invalid = spawnSync( link, [ 'e2e', 'prepare' ], {
+		cwd: directory,
+		env: { ...process.env, E2E_PLUGIN_ZIP: zip, E2E_PHP_VERSION: '8.2.1' },
+		encoding: 'utf8',
+	} );
+	assert.ifError( invalid.error );
+	assert.equal( invalid.status, 1 );
+	assert.match( invalid.stderr, /Invalid E2E_PHP_VERSION/ );
+	assert.ok( ! fs.existsSync( path.join( directory, 'deploy/link-ran' ) ) );
+
 	run( directory, link, [ 'e2e', 'prepare' ], {
 		E2E_PLUGIN_ZIP: zip,
 		E2E_WP_VERSION: '7.0.1',
 		E2E_WC_VERSION: '11.3.0-rc.1',
+		E2E_PHP_VERSION: '8.2',
 	} );
 	assert.equal(
 		fs.readFileSync( path.join( directory, 'deploy/versions' ), 'utf8' ),
-		'7.0.1/11.3.0-rc.1'
+		'7.0.1/11.3.0-rc.1/8.2'
 	);
 	assert.equal(
 		fs.readFileSync(
diff --git a/packages/js/extension-tooling/test/e2e-site-config.test.js b/packages/js/extension-tooling/test/e2e-site-config.test.js
new file mode 100644
index 00000000000..c2f3f4c8899
--- /dev/null
+++ b/packages/js/extension-tooling/test/e2e-site-config.test.js
@@ -0,0 +1,333 @@
+const assert = require( 'node:assert/strict' );
+const fs = require( 'node:fs' );
+const os = require( 'node:os' );
+const path = require( 'node:path' );
+const { test } = require( 'node:test' );
+const writeE2ESiteConfig = require( '@woocommerce/extension-tooling/e2e-site-config' );
+
+const latestWooCommerce =
+	'https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip';
+
+function site( context ) {
+	const root = fs.mkdtempSync( path.join( os.tmpdir(), 'woo-e2e-config-' ) );
+	context.after( () => fs.rmSync( root, { recursive: true, force: true } ) );
+	const defaults = {
+		plugins: [ '.', latestWooCommerce, './fixture' ],
+		core: null,
+		phpVersion: '8.3',
+		mappings: { 'wp-content/mu-plugins/example.php': './example.php' },
+	};
+	const input = path.join( root, '.wp-env.test.json' );
+	fs.writeFileSync( input, JSON.stringify( defaults ) );
+	return {
+		root,
+		defaults,
+		input,
+		output: path.join( root, '.wp-env.e2e.json' ),
+		pluginPath: './deploy/e2e-plugin/example',
+	};
+}
+
+test( 'mounts the packaged plugin and adds a separate debug log', ( context ) => {
+	const { root, pluginPath, defaults, input, output } = site( context );
+	writeE2ESiteConfig( { root, pluginPath, env: {} } );
+	assert.deepEqual( JSON.parse( fs.readFileSync( output, 'utf8' ) ), {
+		...defaults,
+		plugins: [ pluginPath, latestWooCommerce, './fixture' ],
+		mappings: {
+			...defaults.mappings,
+			'./wp-content/debug.log': './tests/_output/e2e-debug.log',
+		},
+	} );
+	assert.deepEqual(
+		JSON.parse( fs.readFileSync( input, 'utf8' ) ),
+		defaults
+	);
+} );
+
+test( 'sets pinned WordPress, WooCommerce and PHP versions', ( context ) => {
+	const { root, pluginPath, input, defaults, output } = site( context );
+	defaults.env = {
+		development: { core: 'WordPress/WordPress#7.0', phpVersion: '8.4' },
+		tests: { phpVersion: '8.3' },
+	};
+	fs.writeFileSync( input, JSON.stringify( defaults ) );
+	writeE2ESiteConfig( {
+		root,
+		pluginPath,
+		env: {
+			WP_VERSION: '7.0.1',
+			WC_VERSION: '11.3.0-rc.1',
+			E2E_PHP_VERSION: '8.2',
+		},
+	} );
+	const config = JSON.parse( fs.readFileSync( output, 'utf8' ) );
+	assert.equal( config.core, 'https://wordpress.org/wordpress-7.0.1.zip' );
+	assert.equal( config.phpVersion, '8.2' );
+	assert.deepEqual( config.env, {
+		development: { core: config.core, phpVersion: config.phpVersion },
+		tests: { phpVersion: '8.3' },
+	} );
+	assert.equal(
+		config.plugins[ 1 ],
+		'https://github.com/woocommerce/woocommerce/releases/download/11.3.0-rc.1/woocommerce.zip'
+	);
+} );
+
+test( 'keeps the configured PHP version when the host exports PHP_VERSION', ( context ) => {
+	const { root, pluginPath, output } = site( context );
+	writeE2ESiteConfig( { root, pluginPath, env: { PHP_VERSION: '8.4.26' } } );
+	const config = JSON.parse( fs.readFileSync( output, 'utf8' ) );
+	assert.equal( config.phpVersion, '8.3' );
+} );
+
+test( 'rejects invalid explicit PHP and WooCommerce versions', ( context ) => {
+	const { root, pluginPath, output } = site( context );
+	fs.writeFileSync( output, '{}' );
+	for ( const [ env, key ] of [
+		[ { E2E_PHP_VERSION: '' }, 'E2E_PHP_VERSION' ],
+		[ { E2E_PHP_VERSION: '8.2.1' }, 'E2E_PHP_VERSION' ],
+		[ { E2E_PHP_VERSION: '8.2-rc.1' }, 'E2E_PHP_VERSION' ],
+		[ { WC_VERSION: '11.3' }, 'WC_VERSION' ],
+		[ { WC_VERSION: 'v11.3.0' }, 'WC_VERSION' ],
+	] ) {
+		assert.throws(
+			() => writeE2ESiteConfig( { root, pluginPath, env } ),
+			( error ) => error.message.includes( key )
+		);
+		assert.equal( fs.readFileSync( output, 'utf8' ), '{}' );
+	}
+} );
+
+test( 'keeps one debug log mount after configuration and development overrides', ( context ) => {
+	const { root, pluginPath, output } = site( context );
+	writeE2ESiteConfig( {
+		root,
+		pluginPath,
+		env: {},
+		configure( config ) {
+			config.mappings = {
+				'wp-content/debug.log': './old.log',
+				'wp-content/mu-plugins/example.php': './example.php',
+			};
+			config.env = {
+				development: {
+					mappings: {
+						'./wp-content/debug.log': './development.log',
+						'wp-content/wp-env.php': './development.php',
+					},
+				},
+				tests: {
+					mappings: { './wp-content/debug.log': './tests.log' },
+				},
+			};
+		},
+	} );
+	const config = JSON.parse( fs.readFileSync( output, 'utf8' ) );
+	assert.deepEqual( config.mappings, {
+		'wp-content/mu-plugins/example.php': './example.php',
+		'./wp-content/debug.log': './tests/_output/e2e-debug.log',
+	} );
+	assert.deepEqual( config.env.development.mappings, {
+		'wp-content/wp-env.php': './development.php',
+	} );
+	assert.deepEqual( config.env.tests.mappings, {
+		'./wp-content/debug.log': './tests.log',
+	} );
+} );
+
+test( 'rejects invalid plugins and mappings before writing a config', ( context ) => {
+	const { root, pluginPath, input, defaults, output } = site( context );
+	for ( const [ overrides, error ] of [
+		[ { plugins: '.' }, 'plugins must be an array of non-empty strings' ],
+		[
+			{ plugins: [ '.', 1 ] },
+			'plugins must be an array of non-empty strings',
+		],
+		[ { mappings: [] }, 'mappings must be an object' ],
+		[
+			{ mappings: { 'wp-content/mu-plugins/custom.php': 42 } },
+			'mappings must be an object of non-empty strings',
+		],
+	] ) {
+		fs.writeFileSync(
+			input,
+			JSON.stringify( { ...defaults, ...overrides } )
+		);
+		assert.throws(
+			() => writeE2ESiteConfig( { root, pluginPath, env: {} } ),
+			( failure ) => failure.message.includes( error )
+		);
+		assert.equal( fs.existsSync( output ), false );
+	}
+} );
+
+test( 'preserves the previous output when a plugin override is invalid', ( context ) => {
+	const { root, pluginPath, output } = site( context );
+	const fixtures = [
+		{
+			configure( config ) {
+				config.plugins.push( undefined );
+			},
+		},
+		{
+			configure( config ) {
+				delete config.plugins[ 2 ];
+			},
+		},
+		{
+			configure( config ) {
+				config.plugins = null;
+			},
+			env: { WC_VERSION: 'nightly' },
+		},
+		...[ '', ' ' ].map( ( source ) => ( {
+			configure( config ) {
+				config.plugins.push( source );
+			},
+		} ) ),
+		{ woocommerce: { latest: 42 } },
+		{ woocommerce: { latest: '' } },
+		{
+			env: { WC_VERSION: 'nightly' },
+			woocommerce: { nightly: '' },
+		},
+	];
+
+	fs.writeFileSync( output, '{}' );
+	for ( const options of fixtures ) {
+		assert.throws(
+			() =>
+				writeE2ESiteConfig( { root, pluginPath, env: {}, ...options } ),
+			( failure ) =>
+				failure.message.includes(
+					'.wp-env.e2e.json plugins must be an array of non-empty strings'
+				)
+		);
+		assert.equal( fs.readFileSync( output, 'utf8' ), '{}' );
+	}
+} );
+
+test( 'preserves the previous output when a mapping override is invalid', ( context ) => {
+	const { root, pluginPath, output } = site( context );
+	fs.writeFileSync( output, '{}' );
+	for ( const mappings of [
+		[],
+		{ 'wp-content/mu-plugins/custom.php': 42 },
+		{ 'wp-content/mu-plugins/custom.php': ' ' },
+	] ) {
+		assert.throws(
+			() =>
+				writeE2ESiteConfig( {
+					root,
+					pluginPath,
+					env: {},
+					configure( config ) {
+						config.mappings = mappings;
+					},
+				} ),
+			( failure ) =>
+				failure.message.includes( '.wp-env.e2e.json mappings' )
+		);
+		assert.equal( fs.readFileSync( output, 'utf8' ), '{}' );
+	}
+} );
+
+test( 'preserves local integration mappings and the WooCommerce nightly mount', ( context ) => {
+	const { root, pluginPath, output } = site( context );
+	const nightly = './deploy/e2e-integrations/woocommerce';
+	writeE2ESiteConfig( {
+		root,
+		pluginPath,
+		env: {
+			WP_VERSION: 'nightly',
+			WC_VERSION: 'nightly',
+			PHP_VERSION: 'nightly',
+		},
+		woocommerce: { nightly },
+		configure( config ) {
+			config.plugins.push( './deploy/e2e-integrations/order-barcodes' );
+			config.mappings[ 'wp-content/mu-plugins/barcodes.php' ] =
+				'./empty.php';
+		},
+	} );
+	const config = JSON.parse( fs.readFileSync( output, 'utf8' ) );
+	assert.equal(
+		config.core,
+		'https://wordpress.org/nightly-builds/wordpress-latest.zip'
+	);
+	assert.equal( config.phpVersion, '8.3' );
+	assert.deepEqual( config.plugins, [
+		pluginPath,
+		nightly,
+		'./fixture',
+		'./deploy/e2e-integrations/order-barcodes',
+	] );
+	assert.equal(
+		config.mappings[ 'wp-content/mu-plugins/barcodes.php' ],
+		'./empty.php'
+	);
+} );
+
+test( 'can override the latest WooCommerce source and add mappings', ( context ) => {
+	const { root, pluginPath, input, defaults, output } = site( context );
+	delete defaults.mappings;
+	fs.writeFileSync( input, JSON.stringify( defaults ) );
+	const latest = 'https://downloads.wordpress.org/plugin/woocommerce.zip';
+	writeE2ESiteConfig( {
+		root,
+		pluginPath,
+		env: { WC_VERSION: 'latest' },
+		woocommerce: { latest },
+	} );
+	const config = JSON.parse( fs.readFileSync( output, 'utf8' ) );
+	assert.equal( config.plugins[ 1 ], latest );
+	assert.deepEqual( config.mappings, {
+		'./wp-content/debug.log': './tests/_output/e2e-debug.log',
+	} );
+} );
+
+test( 'replaces the standard WooCommerce ZIP in a pinned job', ( context ) => {
+	const { root, pluginPath, input, defaults, output } = site( context );
+	defaults.plugins[ 1 ] =
+		'https://downloads.wordpress.org/plugin/woocommerce.zip';
+	fs.writeFileSync( input, JSON.stringify( defaults ) );
+	writeE2ESiteConfig( {
+		root,
+		pluginPath,
+		env: { WC_VERSION: '11.3.0' },
+	} );
+	const config = JSON.parse( fs.readFileSync( output, 'utf8' ) );
+	assert.equal(
+		config.plugins[ 1 ],
+		'https://github.com/woocommerce/woocommerce/releases/download/11.3.0/woocommerce.zip'
+	);
+} );
+
+test( 'rejects a WooCommerce override without a WooCommerce ZIP mount', ( context ) => {
+	const { root, pluginPath, input, defaults, output } = site( context );
+	fs.writeFileSync(
+		input,
+		JSON.stringify( { ...defaults, plugins: [ '.' ] } )
+	);
+	assert.throws(
+		() =>
+			writeE2ESiteConfig( {
+				root,
+				pluginPath,
+				env: { WC_VERSION: 'nightly' },
+			} ),
+		/must include a WooCommerce ZIP mount/
+	);
+	assert.equal( fs.existsSync( output ), false );
+} );
+
+test( 'rejects a missing checkout mount', ( context ) => {
+	const { root, pluginPath, input, defaults, output } = site( context );
+	fs.writeFileSync( input, JSON.stringify( { ...defaults, plugins: [] } ) );
+	assert.throws(
+		() => writeE2ESiteConfig( { root, pluginPath } ),
+		/mount the checkout/
+	);
+	assert.equal( fs.existsSync( output ), false );
+} );