@wordpress/env 10.38.1-next.v.0 → 11.0.0

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( {} );
+		} );
 	} );
 } );

package/lib/download-sources.js

@@ -2,11 +2,11 @@
 /**
  * External dependencies
  */
-const util = require( 'util' );
-const SimpleGit = require( 'simple-git' );
 const fs = require( 'fs' );
-const got = require( 'got' );
 const path = require( 'path' );
+const util = require( 'util' );
+const got = require( 'got' );
+const SimpleGit = require( 'simple-git' );
 
 /**
  * Promisified dependencies
@@ -16,59 +16,9 @@ const extractZip = util.promisify( require( 'extract-zip' ) );
 const { rimraf } = require( 'rimraf' );
 
 /**
- * @typedef {import('./config').WPConfig} WPConfig
  * @typedef {import('./config').WPSource} WPSource
  */
 
-/**
- * Download each source for each environment. If the same source is used in
- * multiple environments, it will only be downloaded once.
- *
- * @param {WPConfig} config  The wp-env configuration object.
- * @param {Object}   spinner The spinner object to show progress.
- * @return {Promise} Returns a promise which resolves when the downloads finish.
- */
-module.exports = function downloadSources( config, spinner ) {
-	const progresses = {};
-	const getProgressSetter = ( id ) => ( progress ) => {
-		progresses[ id ] = progress;
-		spinner.text =
-			'Downloading WordPress.\n' +
-			Object.entries( progresses )
-				.map(
-					( [ key, value ] ) =>
-						`  - ${ key }: ${ ( value * 100 ).toFixed( 0 ) }%`
-				)
-				.join( '\n' );
-	};
-
-	// Will contain a unique array of sources to download.
-	const sources = [];
-	const addedSources = {};
-	const addSource = ( source ) => {
-		if ( source && source.url && ! addedSources[ source.url ] ) {
-			sources.push( source );
-			addedSources[ source.url ] = true;
-		}
-	};
-
-	for ( const env of Object.values( config.env ) ) {
-		env.pluginSources.forEach( addSource );
-		env.themeSources.forEach( addSource );
-		Object.values( env.mappings ).forEach( addSource );
-		addSource( env.coreSource );
-	}
-
-	return Promise.all(
-		sources.map( ( source ) =>
-			downloadSource( source, {
-				onProgress: getProgressSetter( source.basename ),
-				spinner,
-			} )
-		)
-	);
-};
-
 /**
  * Downloads the given source if necessary. The specific action taken depends
  * on the source type. The source is downloaded to source.path.
@@ -204,3 +154,9 @@ async function downloadZipSource( source, { onProgress, spinner, debug } ) {
 
 	onProgress( 1 );
 }
+
+module.exports = {
+	downloadSource,
+	downloadGitSource,
+	downloadZipSource,
+};