@wordpress/env 10.39.0 → 11.0.0

package/lib/config/load-config.js

@@ -11,6 +11,7 @@ const fs = require( 'fs' ).promises;
 const getCacheDirectory = require( './get-cache-directory' );
 const md5 = require( '../md5' );
 const { parseConfig, getConfigFilePath } = require( './parse-config' );
+const { ValidationError } = require( './validate-config' );
 const postProcessConfig = require( './post-process-config' );
 
 /**
@@ -35,12 +36,31 @@ const postProcessConfig = require( './post-process-config' );
 /**
  * Loads any configuration from a given directory.
  *
- * @param {string} configDirectoryPath The directory we want to load the config from.
+ * @param {string}      configDirectoryPath The directory we want to load the config from.
+ * @param {string|null} customConfigPath    Optional custom config file path.
  *
  * @return {Promise<WPConfig>} The config object we've loaded.
  */
-module.exports = async function loadConfig( configDirectoryPath ) {
-	const configFilePath = getConfigFilePath( configDirectoryPath );
+module.exports = async function loadConfig(
+	configDirectoryPath,
+	customConfigPath = null
+) {
+	const configFilePath = getConfigFilePath(
+		configDirectoryPath,
+		'local',
+		customConfigPath
+	);
+
+	// If a custom config path was provided, verify the file exists.
+	if ( customConfigPath ) {
+		try {
+			await fs.stat( configFilePath );
+		} catch ( error ) {
+			throw new ValidationError(
+				`Config file not found: ${ configFilePath }`
+			);
+		}
+	}
 
 	const cacheDirectoryPath = path.resolve(
 		await getCacheDirectory(),
@@ -49,7 +69,11 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 
 	// Parse any configuration we found in the given directory.
 	// This comes merged and prepared for internal consumption.
-	let config = await parseConfig( configDirectoryPath, cacheDirectoryPath );
+	let config = await parseConfig(
+		configDirectoryPath,
+		cacheDirectoryPath,
+		customConfigPath
+	);
 
 	// Make sure to perform any additional post-processing that
 	// may be needed before the config object is ready for
@@ -64,9 +88,15 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 		),
 		configDirectoryPath,
 		workDirectoryPath: cacheDirectoryPath,
+		customConfigPath,
+		testsEnvironment: config.testsEnvironment !== false,
 		detectedLocalConfig: await hasLocalConfig( [
 			configFilePath,
-			getConfigFilePath( configDirectoryPath, 'override' ),
+			getConfigFilePath(
+				configDirectoryPath,
+				'override',
+				customConfigPath
+			),
 		] ),
 		lifecycleScripts: config.lifecycleScripts,
 		env: config.env,

package/lib/config/parse-config.js

@@ -111,22 +111,27 @@ const DEFAULT_ENVIRONMENT_CONFIG = {
  * constructs an object in the format used internally.
  *
  *
- * @param {string} configDirectoryPath A path to the directory we are parsing the config for.
- * @param {string} cacheDirectoryPath  Path to the work directory located in ~/.wp-env.
+ * @param {string}      configDirectoryPath A path to the directory we are parsing the config for.
+ * @param {string}      cacheDirectoryPath  Path to the work directory located in ~/.wp-env.
+ * @param {string|null} customConfigPath    Optional custom config file path.
  *
  * @return {Promise<WPRootConfig>} Parsed config.
  */
-async function parseConfig( configDirectoryPath, cacheDirectoryPath ) {
+async function parseConfig(
+	configDirectoryPath,
+	cacheDirectoryPath,
+	customConfigPath = null
+) {
 	// The local config will be used to override any defaults.
 	const localConfig = await parseConfigFile(
-		getConfigFilePath( configDirectoryPath ),
+		getConfigFilePath( configDirectoryPath, 'local', customConfigPath ),
 		{ cacheDirectoryPath }
 	);
 
 	// Any overrides that can be used in place
 	// of properties set by the local config.
 	const overrideConfig = await parseConfigFile(
-		getConfigFilePath( configDirectoryPath, 'override' ),
+		getConfigFilePath( configDirectoryPath, 'override', customConfigPath ),
 		{ cacheDirectoryPath }
 	);
 
@@ -161,27 +166,37 @@ async function parseConfig( configDirectoryPath, cacheDirectoryPath ) {
 /**
  * Gets the path to the config file.
  *
- * @param {string} configDirectoryPath The path to the directory containing config files.
- * @param {string} type                The type of config file we're interested in: 'local' or 'override'.
+ * @param {string}      configDirectoryPath The path to the directory containing config files.
+ * @param {string}      type                The type of config file we're interested in: 'local' or 'override'.
+ * @param {string|null} customConfigPath    Optional custom config file path (only used for 'local' type).
  *
  * @return {string} The path to the config file.
  */
-function getConfigFilePath( configDirectoryPath, type = 'local' ) {
-	let fileName;
-	switch ( type ) {
-		case 'local': {
-			fileName = '.wp-env.json';
-			break;
-		}
+function getConfigFilePath(
+	configDirectoryPath,
+	type = 'local',
+	customConfigPath = null
+) {
+	// If a custom config path is provided for the local config, use it.
+	if ( type === 'local' && customConfigPath ) {
+		return path.resolve( customConfigPath );
+	}
 
-		case 'override': {
-			fileName = '.wp-env.override.json';
-			break;
-		}
+	// For override, derive from custom config: staging.json -> staging.override.json
+	if ( type === 'override' && customConfigPath ) {
+		const resolved = path.resolve( customConfigPath );
+		const ext = path.extname( resolved );
+		const base = path.basename( resolved, ext );
+		const dir = path.dirname( resolved );
+		return path.join( dir, `${ base }.override${ ext }` );
+	}
 
-		default: {
-			throw new Error( `Invalid config file type "${ type }.` );
-		}
+	// Default behavior.
+	const fileName =
+		type === 'local' ? '.wp-env.json' : '.wp-env.override.json';
+
+	if ( type !== 'local' && type !== 'override' ) {
+		throw new Error( `Invalid config file type "${ type }.` );
 	}
 
 	return path.resolve( configDirectoryPath, fileName );
@@ -235,6 +250,8 @@ async function getDefaultConfig(
 		lifecycleScripts: {
 			afterStart: null,
 			afterClean: null,
+			afterReset: null,
+			afterCleanup: null,
 			afterDestroy: null,
 		},
 		env: {
@@ -312,6 +329,12 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 		overrideConfig.env.tests.phpVersion = overrides.phpVersion;
 	}
 
+	if ( overrides.multisite ) {
+		overrideConfig.multisite = overrides.multisite;
+		overrideConfig.env.development.multisite = overrides.multisite;
+		overrideConfig.env.tests.multisite = overrides.multisite;
+	}
+
 	return overrideConfig;
 }
 
@@ -359,6 +382,14 @@ async function parseRootConfig( configFile, rawConfig, options ) {
 		checkPort( configFile, `testsPort`, rawConfig.testsPort );
 		parsedConfig.testsPort = rawConfig.testsPort;
 	}
+	if ( rawConfig.testsEnvironment !== undefined ) {
+		if ( typeof rawConfig.testsEnvironment !== 'boolean' ) {
+			throw new ValidationError(
+				`Invalid ${ configFile }: "testsEnvironment" must be a boolean.`
+			);
+		}
+		parsedConfig.testsEnvironment = rawConfig.testsEnvironment;
+	}
 	parsedConfig.lifecycleScripts = {};
 	if ( rawConfig.lifecycleScripts ) {
 		checkObjectWithValues(
@@ -436,6 +467,7 @@ async function parseEnvironmentConfig(
 		// configuration options that we will parse.
 		switch ( key ) {
 			case 'testsPort':
+			case 'testsEnvironment':
 			case 'lifecycleScripts':
 			case 'env': {
 				if ( options.rootConfig ) {

package/lib/config/post-process-config.js

@@ -39,25 +39,32 @@ module.exports = function postProcessConfig( config ) {
  * @return {WPRootConfig} The config object with the root options merged together with the environment-specific options.
  */
 function mergeRootToEnvironments( config ) {
+	const testsDisabled = config.testsEnvironment === false;
+
 	// Some root-level options need to be handled early because they have a special
 	// cascade behavior that would break the normal merge. After merging we then
 	// delete them to avoid that breakage and add them back before we return.
 	const removedRootOptions = {};
-	if (
-		config.port !== undefined &&
-		config.env.development.port === undefined
-	) {
-		removedRootOptions.port = config.port;
-		config.env.development.port = config.port;
-		delete config.port;
-	}
-	if (
-		config.testsPort !== undefined &&
-		config.env.tests.port === undefined
-	) {
-		removedRootOptions.testsPort = config.testsPort;
-		config.env.tests.port = config.testsPort;
-		delete config.testsPort;
+
+	// When tests are disabled, the env key is ignored entirely since there
+	// is only one environment. All config should be at the root level.
+	if ( ! testsDisabled ) {
+		if (
+			config.port !== undefined &&
+			config.env.development.port === undefined
+		) {
+			removedRootOptions.port = config.port;
+			config.env.development.port = config.port;
+			delete config.port;
+		}
+		if (
+			config.testsPort !== undefined &&
+			config.env.tests.port === undefined
+		) {
+			removedRootOptions.testsPort = config.testsPort;
+			config.env.tests.port = config.testsPort;
+			delete config.testsPort;
+		}
 	}
 	if ( config.lifecycleScripts !== undefined ) {
 		removedRootOptions.lifecycleScripts = config.lifecycleScripts;
@@ -67,9 +74,15 @@ function mergeRootToEnvironments( config ) {
 	// Merge the root config and the environment configs together so that
 	// we can ignore the root config and have full environment configs.
 	for ( const env in config.env ) {
+		// Skip merging root options into the tests environment when it's disabled.
+		if ( env === 'tests' && testsDisabled ) {
+			continue;
+		}
 		config.env[ env ] = mergeConfigs(
 			deepCopyRootOptions( config ),
-			config.env[ env ]
+			// When tests are disabled, ignore env overrides — all config
+			// should be specified at the root level.
+			testsDisabled ? {} : config.env[ env ]
 		);
 	}
 
@@ -89,12 +102,16 @@ function mergeRootToEnvironments( config ) {
  * @return {WPRootConfig} The config after post-processing.
  */
 function appendPortToWPConfigs( config ) {
+	const testsDisabled = config.testsEnvironment === false;
 	const options = [ 'WP_TESTS_DOMAIN', 'WP_SITEURL', 'WP_HOME' ];
 
 	// We are only interested in editing the config options for environment-specific configs.
 	// If we made this change to the root config it would cause problems since they would
 	// be mapped to all environments even though the ports will be different.
 	for ( const env in config.env ) {
+		if ( env === 'tests' && testsDisabled ) {
+			continue;
+		}
 		// There's nothing to do without any wp-config options set.
 		if ( config.env[ env ].config === undefined ) {
 			continue;
@@ -128,6 +145,8 @@ function appendPortToWPConfigs( config ) {
  * @param {WPRootConfig} config The config to process.
  */
 function validatePortUniqueness( config ) {
+	const testsDisabled = config.testsEnvironment === false;
+
 	// We're going to build a map of the environments and their port
 	// so we can accommodate root-level config options more easily.
 	const environmentPorts = {};
@@ -135,6 +154,9 @@ function validatePortUniqueness( config ) {
 	// Add all of the environments to the map. This will
 	// overwrite any root-level options if necessary.
 	for ( const env in config.env ) {
+		if ( env === 'tests' && testsDisabled ) {
+			continue;
+		}
 		if ( config.env[ env ].port === undefined ) {
 			throw new ValidationError(
 				`The "${ env }" environment has an invalid port.`

package/lib/config/test/__snapshots__/config-integration.js.snap

@@ -3,6 +3,7 @@
 exports[`Config Integration should load local and override configuration files 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -71,10 +72,13 @@ exports[`Config Integration should load local and override configuration files 1
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": "test",
+    "afterReset": null,
     "afterStart": null,
   },
   "name": "gutenberg",
+  "testsEnvironment": true,
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }
 `;
@@ -82,6 +86,7 @@ exports[`Config Integration should load local and override configuration files 1
 exports[`Config Integration should load local configuration file 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -150,10 +155,13 @@ exports[`Config Integration should load local configuration file 1`] = `
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": "test",
   },
   "name": "gutenberg",
+  "testsEnvironment": true,
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }
 `;
@@ -161,6 +169,7 @@ exports[`Config Integration should load local configuration file 1`] = `
 exports[`Config Integration should use default configuration 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -229,10 +238,13 @@ exports[`Config Integration should use default configuration 1`] = `
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": null,
   },
   "name": "gutenberg",
+  "testsEnvironment": true,
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }
 `;
@@ -240,6 +252,7 @@ exports[`Config Integration should use default configuration 1`] = `
 exports[`Config Integration should use environment variables over local and override configuration files 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -310,10 +323,13 @@ exports[`Config Integration should use environment variables over local and over
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": "test",
   },
   "name": "gutenberg",
+  "testsEnvironment": true,
   "workDirectoryPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338",
 }
 `;

package/lib/config/test/parse-config.js

@@ -52,6 +52,8 @@ const DEFAULT_CONFIG = {
 	lifecycleScripts: {
 		afterStart: null,
 		afterClean: null,
+		afterReset: null,
+		afterCleanup: null,
 		afterDestroy: null,
 	},
 	env: {
@@ -455,4 +457,35 @@ describe( 'parseConfig', () => {
 		};
 		expect( parsed.env ).toEqual( expected );
 	} );
+
+	it( 'should accept testsEnvironment as a boolean', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					testsEnvironment: false,
+				};
+			}
+		} );
+
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
+		expect( parsed.testsEnvironment ).toEqual( false );
+	} );
+
+	it( 'throws for non-boolean testsEnvironment', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					testsEnvironment: 'false',
+				};
+			}
+		} );
+
+		await expect(
+			parseConfig( '/test/gutenberg', '/cache' )
+		).rejects.toEqual(
+			new ValidationError(
+				`Invalid /test/gutenberg/.wp-env.json: "testsEnvironment" must be a boolean.`
+			)
+		);
+	} );
 } );

package/lib/config/test/post-process-config.js

@@ -295,5 +295,57 @@ describe( 'postProcessConfig', () => {
 				)
 			);
 		} );
+
+		it( 'should skip port validation for disabled tests environment', () => {
+			expect( () => {
+				postProcessConfig( {
+					testsEnvironment: false,
+					port: 123,
+					env: {
+						development: {},
+						tests: {},
+					},
+				} );
+			} ).not.toThrow();
+		} );
+	} );
+
+	describe( 'testsEnvironment', () => {
+		it( 'should ignore env overrides entirely when testsEnvironment is false', () => {
+			const processed = postProcessConfig( {
+				testsEnvironment: false,
+				port: 123,
+				testsPort: 456,
+				coreSource: {
+					type: 'test',
+				},
+				config: {
+					TESTS_ROOT: 'root',
+				},
+				pluginSources: [
+					{
+						type: 'root-plugin',
+					},
+				],
+				env: {
+					development: {
+						config: {
+							TEST_ENV: 'development',
+						},
+					},
+					tests: {},
+				},
+			} );
+
+			// Development should get root options but NOT env overrides.
+			expect( processed.env.development.port ).toEqual( 123 );
+			expect( processed.env.development.config.TESTS_ROOT ).toEqual(
+				'root'
+			);
+			expect( processed.env.development.config.TEST_ENV ).toBeUndefined();
+
+			// Tests should not get root options merged.
+			expect( processed.env.tests ).toEqual( {} );
+		} );
 	} );
 } );