@wordpress/env 10.39.0 → 11.0.0

package/lib/runtime/docker/index.js

@@ -11,7 +11,6 @@ const { rimraf } = require( 'rimraf' );
 /**
  * Promisified dependencies
  */
-const sleep = util.promisify( setTimeout );
 const exec = util.promisify( require( 'child_process' ).exec );
 
 /**
@@ -26,7 +25,6 @@ const {
 	validateRunContainer,
 } = require( './validate-run-container' );
 const {
-	checkDatabaseConnection,
 	configureWordPress,
 	resetDatabase,
 	setupWordPressDirectories,
@@ -109,8 +107,11 @@ class DockerRuntime {
 			xdebug,
 			spx,
 			writeChanges: true,
+			customConfigPath: config.customConfigPath,
 		} );
 
+		const testsEnabled = fullConfig.testsEnvironment !== false;
+
 		// Check if the hash of the config has changed. If so, run configuration.
 		const configHash = md5( fullConfig );
 		const { workDirectoryPath, dockerComposeConfigPath } = fullConfig;
@@ -139,13 +140,19 @@ class DockerRuntime {
 		 * the container before continuing allows the docker entrypoint script,
 		 * which restores the files, to run again when we start the containers.
 		 *
-		 * Additionally, this serves as a way to restart the container entirely
-		 * should the need arise.
+		 * Additionally, --remove-orphans ensures containers from services that
+		 * were removed in the new config (e.g., tests-* after setting
+		 * testsEnvironment: false) are properly stopped.
 		 *
 		 * @see https://github.com/WordPress/gutenberg/pull/20253#issuecomment-587228440
 		 */
 		if ( shouldConfigureWp ) {
-			await this.stop( fullConfig, { spinner, debug } );
+			spinner.text = 'Stopping WordPress.';
+			await dockerCompose.down( {
+				config: dockerComposeConfigPath,
+				log: debug,
+				commandOptions: [ '--remove-orphans' ],
+			} );
 			// Update the images before starting the services again.
 			spinner.text = 'Updating docker images.';
 
@@ -156,7 +163,9 @@ class DockerRuntime {
 			// as docker volumes, simply updating the image will not change those
 			// files. Thus, we need to remove those volumes in order for the files
 			// to be updated when pulling the new images.
-			const volumesToRemove = `${ directoryHash }_wordpress ${ directoryHash }_tests-wordpress`;
+			const volumesToRemove = testsEnabled
+				? `${ directoryHash }_wordpress ${ directoryHash }_tests-wordpress`
+				: `${ directoryHash }_wordpress`;
 
 			try {
 				if ( fullConfig.debug ) {
@@ -173,8 +182,12 @@ class DockerRuntime {
 			spinner.text = 'Downloading sources.';
 		}
 
+		const mysqlServices = [ 'mysql' ];
+		if ( testsEnabled ) {
+			mysqlServices.push( 'tests-mysql' );
+		}
 		await Promise.all( [
-			dockerCompose.upOne( 'mysql', {
+			dockerCompose.upMany( mysqlServices, {
 				...dockerComposeConfig,
 				commandOptions: shouldConfigureWp
 					? [ '--build', '--force-recreate' ]
@@ -189,37 +202,44 @@ class DockerRuntime {
 			await setupWordPressDirectories( fullConfig );
 
 			// Use the WordPress versions to download the PHPUnit suite.
-			const wpVersions = await Promise.all( [
+			const wpVersionPromises = [
 				readWordPressVersion(
 					fullConfig.env.development.coreSource,
 					spinner,
 					debug
 				),
-				readWordPressVersion(
-					fullConfig.env.tests.coreSource,
-					spinner,
-					debug
-				),
-			] );
-			await downloadWPPHPUnit(
-				fullConfig,
-				{ development: wpVersions[ 0 ], tests: wpVersions[ 1 ] },
-				spinner,
-				debug
-			);
+			];
+			if ( testsEnabled ) {
+				wpVersionPromises.push(
+					readWordPressVersion(
+						fullConfig.env.tests.coreSource,
+						spinner,
+						debug
+					)
+				);
+			}
+			const wpVersions = await Promise.all( wpVersionPromises );
+			const wpVersionMap = {
+				development: wpVersions[ 0 ],
+			};
+			if ( testsEnabled ) {
+				wpVersionMap.tests = wpVersions[ 1 ];
+			}
+			await downloadWPPHPUnit( fullConfig, wpVersionMap, spinner, debug );
 		}
 
 		spinner.text = 'Starting WordPress.';
 
-		await dockerCompose.upMany(
-			[ 'wordpress', 'tests-wordpress', 'cli', 'tests-cli' ],
-			{
-				...dockerComposeConfig,
-				commandOptions: shouldConfigureWp
-					? [ '--build', '--force-recreate' ]
-					: [],
-			}
-		);
+		const wpServices = [ 'wordpress', 'cli' ];
+		if ( testsEnabled ) {
+			wpServices.push( 'tests-wordpress', 'tests-cli' );
+		}
+		await dockerCompose.upMany( wpServices, {
+			...dockerComposeConfig,
+			commandOptions: shouldConfigureWp
+				? [ '--build', '--force-recreate' ]
+				: [],
+		} );
 
 		if ( fullConfig.env.development.phpmyadminPort ) {
 			await dockerCompose.upOne( 'phpmyadmin', {
@@ -230,7 +250,7 @@ class DockerRuntime {
 			} );
 		}
 
-		if ( fullConfig.env.tests.phpmyadminPort ) {
+		if ( testsEnabled && fullConfig.env.tests.phpmyadminPort ) {
 			await dockerCompose.upOne( 'tests-phpmyadmin', {
 				...dockerComposeConfig,
 				commandOptions: shouldConfigureWp
@@ -250,21 +270,8 @@ class DockerRuntime {
 		if ( shouldConfigureWp ) {
 			spinner.text = 'Configuring WordPress.';
 
-			try {
-				await checkDatabaseConnection( fullConfig );
-			} catch ( error ) {
-				// Wait 30 seconds for MySQL to accept connections.
-				await retry( () => checkDatabaseConnection( fullConfig ), {
-					times: 30,
-					delay: 1000,
-				} );
-
-				// It takes 3-4 seconds for MySQL to be ready after it starts accepting connections.
-				await sleep( 4000 );
-			}
-
 			// Retry WordPress installation in case MySQL *still* wasn't ready.
-			await Promise.all( [
+			const configTasks = [
 				retry(
 					() =>
 						configureWordPress(
@@ -276,13 +283,19 @@ class DockerRuntime {
 						times: 2,
 					}
 				),
-				retry(
-					() => configureWordPress( 'tests', fullConfig, spinner ),
-					{
-						times: 2,
-					}
-				),
-			] );
+			];
+			if ( testsEnabled ) {
+				configTasks.push(
+					retry(
+						() =>
+							configureWordPress( 'tests', fullConfig, spinner ),
+						{
+							times: 2,
+						}
+					)
+				);
+			}
+			await Promise.all( configTasks );
 
 			// Set the cache key once everything has been configured.
 			await setCache( CONFIG_CACHE_KEY, configHash, {
@@ -292,7 +305,6 @@ class DockerRuntime {
 
 		// Get port information for the result message
 		const siteUrl = fullConfig.env.development.config.WP_SITEURL;
-		const testsSiteUrl = fullConfig.env.tests.config.WP_SITEURL;
 
 		const mySQLPort = await this._getPublicDockerPort(
 			'mysql',
@@ -300,12 +312,6 @@ class DockerRuntime {
 			dockerComposeConfig
 		);
 
-		const testsMySQLPort = await this._getPublicDockerPort(
-			'tests-mysql',
-			3306,
-			dockerComposeConfig
-		);
-
 		const phpmyadminPort = fullConfig.env.development.phpmyadminPort
 			? await this._getPublicDockerPort(
 					'phpmyadmin',
@@ -314,31 +320,42 @@ class DockerRuntime {
 			  )
 			: null;
 
-		const testsPhpmyadminPort = fullConfig.env.tests.phpmyadminPort
-			? await this._getPublicDockerPort(
-					'tests-phpmyadmin',
-					80,
-					dockerComposeConfig
-			  )
-			: null;
-
 		const message = [
 			'WordPress development site started' +
 				( siteUrl ? ` at ${ siteUrl }` : '.' ),
-			'WordPress test site started' +
-				( testsSiteUrl ? ` at ${ testsSiteUrl }` : '.' ),
 			`MySQL is listening on port ${ mySQLPort }`,
-			`MySQL for automated testing is listening on port ${ testsMySQLPort }`,
 			phpmyadminPort &&
 				`phpMyAdmin started at http://localhost:${ phpmyadminPort }`,
-			testsPhpmyadminPort &&
-				`phpMyAdmin for automated testing started at http://localhost:${ testsPhpmyadminPort }`,
-		]
-			.filter( Boolean )
-			.join( '\n' );
+		];
+
+		if ( testsEnabled ) {
+			const testsSiteUrl = fullConfig.env.tests.config.WP_SITEURL;
+			const testsMySQLPort = await this._getPublicDockerPort(
+				'tests-mysql',
+				3306,
+				dockerComposeConfig
+			);
+			const testsPhpmyadminPort = fullConfig.env.tests.phpmyadminPort
+				? await this._getPublicDockerPort(
+						'tests-phpmyadmin',
+						80,
+						dockerComposeConfig
+				  )
+				: null;
+
+			message.push(
+				'WordPress test site started' +
+					( testsSiteUrl ? ` at ${ testsSiteUrl }` : '.' ),
+				`MySQL for automated testing is listening on port ${ testsMySQLPort }`,
+				testsPhpmyadminPort &&
+					`phpMyAdmin for automated testing started at http://localhost:${ testsPhpmyadminPort }`
+			);
+		}
+
+		const formattedMessage = message.filter( Boolean ).join( '\n' );
 
 		return {
-			message,
+			message: formattedMessage,
 			siteUrl,
 		};
 	}
@@ -369,6 +386,15 @@ class DockerRuntime {
 		return 'WARNING! This will remove Docker containers, volumes, networks, and images associated with the WordPress instance.';
 	}
 
+	/**
+	 * Get the warning message for cleanup confirmation.
+	 *
+	 * @return {string} Warning message.
+	 */
+	getCleanupWarningMessage() {
+		return 'WARNING! This will remove Docker containers, volumes, networks, and local files associated with the WordPress instance. Docker images will be preserved.';
+	}
+
 	/**
 	 * Stop the Docker containers.
 	 *
@@ -381,6 +407,7 @@ class DockerRuntime {
 		const { dockerComposeConfigPath } = await initConfig( {
 			spinner,
 			debug,
+			customConfigPath: config.customConfigPath,
 		} );
 
 		spinner.text = 'Stopping WordPress.';
@@ -413,7 +440,8 @@ class DockerRuntime {
 		spinner.text = 'Removing local files.';
 		// Note: there is a race condition where docker compose actually hasn't finished
 		// by this point, which causes rimraf to fail. We need to wait at least 2.5-5s,
-		// but using 10s in case it's dependant on the machine.
+		// but using 10s in case it's dependent on the machine. Removing images takes
+		// longer so we use a longer wait time here.
 		await new Promise( ( resolve ) => setTimeout( resolve, 10000 ) );
 		await rimraf( config.workDirectoryPath );
 
@@ -421,27 +449,79 @@ class DockerRuntime {
 	}
 
 	/**
-	 * Clean/reset the WordPress database.
+	 * Cleanup the Docker containers and remove local files, but preserve images.
+	 *
+	 * @param {WPConfig} config          The wp-env config object.
+	 * @param {Object}   options         Cleanup options.
+	 * @param {Object}   options.spinner A CLI spinner which indicates progress.
+	 * @param {boolean}  options.debug   True if debug mode is enabled.
+	 */
+	async cleanup( config, { spinner, debug } ) {
+		spinner.text = 'Removing docker containers, volumes, and networks.';
+
+		await dockerCompose.down( {
+			config: config.dockerComposeConfigPath,
+			commandOptions: [ '--volumes', '--remove-orphans' ],
+			log: debug,
+		} );
+
+		spinner.text = 'Removing local files.';
+		// Note: there is a race condition where docker compose actually hasn't finished
+		// by this point, which causes rimraf to fail. We need to wait at least 2.5-5s,
+		// but since we're not removing images, the wait can be shorter.
+		await new Promise( ( resolve ) => setTimeout( resolve, 3000 ) );
+		await rimraf( config.workDirectoryPath );
+
+		spinner.text = 'Cleaned up WordPress environment.';
+	}
+
+	/**
+	 * Reset the WordPress database.
 	 *
 	 * @param {WPConfig} config              The wp-env config object.
-	 * @param {Object}   options             Clean options.
-	 * @param {string}   options.environment The environment to clean.
+	 * @param {Object}   options             Reset options.
+	 * @param {string}   options.environment The environment to reset.
 	 * @param {Object}   options.spinner     A CLI spinner which indicates progress.
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
 	async clean( config, { environment, spinner, debug } ) {
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
+
+		const testsEnabled = fullConfig.testsEnvironment !== false;
+
+		if ( ! testsEnabled && environment === 'tests' ) {
+			throw new Error(
+				'Cannot reset the tests environment because it is disabled in the configuration.'
+			);
+		}
 
 		const description = `${ environment } environment${
 			environment === 'all' ? 's' : ''
 		}`;
-		spinner.text = `Cleaning ${ description }.`;
+		spinner.text = `Resetting ${ description }.`;
 
 		const tasks = [];
 
-		// Start the database first to avoid race conditions where all tasks create
-		// different docker networks with the same name.
-		await dockerCompose.upOne( 'mysql', {
+		// Start the appropriate MySQL service(s) first to avoid race conditions
+		// where parallel tasks try to create docker networks with the same name.
+		// The dependency chain (cli -> wordpress -> mysql with service_healthy)
+		// ensures MySQL is ready before database operations run.
+		const mysqlServices = [];
+		if ( environment === 'all' || environment === 'development' ) {
+			mysqlServices.push( 'mysql' );
+		}
+		if (
+			testsEnabled &&
+			( environment === 'all' || environment === 'tests' )
+		) {
+			mysqlServices.push( 'tests-mysql' );
+		}
+
+		await dockerCompose.upMany( mysqlServices, {
 			config: fullConfig.dockerComposeConfigPath,
 			log: fullConfig.debug,
 		} );
@@ -456,7 +536,10 @@ class DockerRuntime {
 			);
 		}
 
-		if ( environment === 'all' || environment === 'tests' ) {
+		if (
+			testsEnabled &&
+			( environment === 'all' || environment === 'tests' )
+		) {
 			tasks.push(
 				resetDatabase( 'tests', fullConfig )
 					.then( () => configureWordPress( 'tests', fullConfig ) )
@@ -466,7 +549,7 @@ class DockerRuntime {
 
 		await Promise.all( tasks );
 
-		spinner.text = `Cleaned ${ description }.`;
+		spinner.text = `Reset ${ description }.`;
 	}
 
 	/**
@@ -493,7 +576,20 @@ class DockerRuntime {
 		// Validate the container name (throws for deprecated containers)
 		validateRunContainer( container );
 
-		const fullConfig = await initConfig( { spinner, debug } );
+		if (
+			config.testsEnvironment === false &&
+			container.startsWith( 'tests-' )
+		) {
+			throw new Error(
+				`Cannot run commands on "${ container }" because the tests environment is disabled in the configuration.`
+			);
+		}
+
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 
 		// Shows a contextual tip for the given command.
 		const joinedCommand = command.join( ' ' );
@@ -520,7 +616,19 @@ class DockerRuntime {
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
 	async logs( config, { environment, watch, spinner, debug } ) {
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
+
+		const testsEnabled = fullConfig.testsEnvironment !== false;
+
+		if ( ! testsEnabled && environment === 'tests' ) {
+			throw new Error(
+				'Cannot show logs for the tests environment because it is disabled in the configuration.'
+			);
+		}
 
 		// If we show text while watching the logs, it will continue showing up every
 		// few lines in the logs as they happen, which isn't a good look. So only
@@ -529,10 +637,16 @@ class DockerRuntime {
 			spinner.text = `Showing logs for the ${ environment } environment.`;
 		}
 
-		const servicesToWatch =
-			environment === 'all'
+		let servicesToWatch;
+		if ( environment === 'all' ) {
+			servicesToWatch = testsEnabled
 				? [ 'tests-wordpress', 'wordpress' ]
-				: [ environment === 'tests' ? 'tests-wordpress' : 'wordpress' ];
+				: [ 'wordpress' ];
+		} else {
+			servicesToWatch = [
+				environment === 'tests' ? 'tests-wordpress' : 'wordpress',
+			];
+		}
 
 		const output = await Promise.all( [
 			...servicesToWatch.map( ( service ) =>
@@ -577,6 +691,82 @@ class DockerRuntime {
 		spinner.text = 'Finished showing logs.';
 	}
 
+	/**
+	 * Get the status of the Docker environment.
+	 *
+	 * @param {WPConfig} config          The wp-env config object.
+	 * @param {Object}   options         Status options.
+	 * @param {Object}   options.spinner A CLI spinner which indicates progress.
+	 * @param {boolean}  options.debug   True if debug mode is enabled.
+	 * @return {Promise<Object>} Status object with environment information.
+	 */
+	async getStatus( config, { spinner, debug } ) {
+		spinner.text = 'Getting environment status.';
+
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
+		const dockerComposeConfig = {
+			config: fullConfig.dockerComposeConfigPath,
+			log: debug,
+		};
+
+		// Check if containers are running by trying to get a port.
+		let isRunning = false;
+		let mySQLPort = null;
+		let phpmyadminPort = null;
+
+		try {
+			mySQLPort = await this._getPublicDockerPort(
+				'mysql',
+				3306,
+				dockerComposeConfig
+			);
+			isRunning = true;
+
+			if ( fullConfig.env.development.phpmyadminPort ) {
+				phpmyadminPort = await this._getPublicDockerPort(
+					'phpmyadmin',
+					80,
+					dockerComposeConfig
+				);
+			}
+		} catch {
+			// Containers are not running.
+		}
+
+		const siteUrl = fullConfig.env.development.config.WP_SITEURL;
+
+		const testsEnabled = fullConfig.testsEnvironment !== false;
+
+		return {
+			status: isRunning ? 'running' : 'stopped',
+			runtime: 'docker',
+			urls: {
+				development: isRunning ? siteUrl : null,
+				phpmyadmin:
+					isRunning && phpmyadminPort
+						? `http://localhost:${ phpmyadminPort }`
+						: null,
+			},
+			ports: {
+				development: fullConfig.env.development.port,
+				...( testsEnabled && {
+					tests: fullConfig.env.tests.port,
+				} ),
+				mysql: mySQLPort,
+			},
+			config: {
+				multisite: fullConfig.env.development.multisite,
+				xdebug: fullConfig.xdebug || 'off',
+			},
+			configPath: fullConfig.configDirectoryPath,
+			installPath: fullConfig.workDirectoryPath,
+		};
+	}
+
 	/**
 	 * Runs an arbitrary command on the given Docker container.
 	 *

package/lib/runtime/docker/init-config.js

@@ -22,16 +22,17 @@ const buildDockerComposeConfig = require( './build-docker-compose-config' );
  * ./.wp-env.json, creates ~/.wp-env, ~/.wp-env/docker-compose.yml, and
  * ~/.wp-env/Dockerfile.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner      A CLI spinner which indicates progress.
- * @param {boolean} options.debug        True if debug mode is enabled.
- * @param {string}  options.xdebug       The Xdebug mode to set. Defaults to "off".
- * @param {string}  options.spx          The SPX mode to set. Defaults to "off".
- * @param {boolean} options.writeChanges If true, writes the parsed config to the
- *                                       required docker files like docker-compose
- *                                       and Dockerfile. By default, this is false
- *                                       and only the `start` command writes any
- *                                       changes.
+ * @param {Object}      options
+ * @param {Object}      options.spinner          A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug            True if debug mode is enabled.
+ * @param {string}      options.xdebug           The Xdebug mode to set. Defaults to "off".
+ * @param {string}      options.spx              The SPX mode to set. Defaults to "off".
+ * @param {boolean}     options.writeChanges     If true, writes the parsed config to the
+ *                                               required docker files like docker-compose
+ *                                               and Dockerfile. By default, this is false
+ *                                               and only the `start` command writes any
+ *                                               changes.
+ * @param {string|null} options.customConfigPath Path to a custom .wp-env.json configuration file.
  * @return {WPConfig} The-env config object.
  */
 module.exports = async function initConfig( {
@@ -40,8 +41,9 @@ module.exports = async function initConfig( {
 	xdebug = 'off',
 	spx = 'off',
 	writeChanges = false,
+	customConfigPath = null,
 } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	config.debug = debug;
 
 	// Adding this to the config allows the start command to understand that the
@@ -87,10 +89,16 @@ module.exports = async function initConfig( {
 			yaml.dump( dockerComposeConfig )
 		);
 
-		// Write four Dockerfiles for each service we provided.
+		// Write Dockerfiles for each service we provided.
 		// (WordPress and CLI services, then a development and test environment for each.)
 		for ( const imageType of [ 'WordPress', 'CLI' ] ) {
 			for ( const envType of [ 'development', 'tests' ] ) {
+				if (
+					envType === 'tests' &&
+					config.testsEnvironment === false
+				) {
+					continue;
+				}
 				await writeFile(
 					path.resolve(
 						config.workDirectoryPath,

package/lib/runtime/docker/wordpress.js

@@ -47,20 +47,6 @@ function isWPMajorMinorVersionLower( version, compareVersion ) {
 	return versionNumber < compareVersionNumber;
 }
 
-/**
- * Checks a WordPress database connection. An error is thrown if the test is
- * unsuccessful.
- *
- * @param {WPConfig} config The wp-env config object.
- */
-async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) {
-	await dockerCompose.run( 'cli', 'wp db check', {
-		config: dockerComposeConfigPath,
-		commandOptions: [ '--rm' ],
-		log: debug,
-	} );
-}
-
 /**
  * Configures WordPress for the given environment by installing WordPress,
  * activating all plugins, and activating the first theme. These steps are
@@ -316,7 +302,6 @@ async function copyCoreFiles( fromPath, toPath ) {
 }
 
 module.exports = {
-	checkDatabaseConnection,
 	configureWordPress,
 	resetDatabase,
 	setupWordPressDirectories,

package/lib/runtime/errors.js

@@ -12,6 +12,17 @@ class UnsupportedCommandError extends Error {
 	}
 }
 
+/**
+ * Error thrown when the environment has not been initialized.
+ */
+class EnvironmentNotInitializedError extends Error {
+	constructor() {
+		super( 'Environment not initialized. Run `wp-env start` first.' );
+		this.name = 'EnvironmentNotInitializedError';
+	}
+}
+
 module.exports = {
 	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
 };