wp-env: Allow to set WordPress (Docker image) version

.wp-env.json

@@ -5,11 +5,15 @@
 	],
 	"themes": [ "WordPress/theme-experiments/tt1-blocks#tt1-blocks@0.4.3" ],
 	"env": {
+		"development": {
+			"wpVersion": "5.7"
+		},
 		"tests": {
 			"mappings": {
 				"wp-content/mu-plugins": "./packages/e2e-tests/mu-plugins",
 				"wp-content/plugins/gutenberg-test-plugins": "./packages/e2e-tests/plugins"
-			}
+			},
+			"wpVersion": "5.7"
 		}
 	}
 }

packages/env/README.md

@@ -384,6 +384,7 @@ You can customize the WordPress installation, plugins and themes that the develo
 | Field          | Type           | Default                                | Description                                                                                                                      |
 | -------------- | -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | `"core"`       | `string\|null` | `null`                                 | The WordPress installation to use. If `null` is specified, `wp-env` will use the latest production release of WordPress.         |
+| `"wpVersion"`  | `string\|null` | `null`                                 | The WordPress version to use (for the Docker image). If `null` is specified, `wp-env` will use the production release of WordPress. |
 | `"phpVersion"` | `string\|null` | `null`                                 | The PHP version to use. If `null` is specified, `wp-env` will use the default version used with production release of WordPress. |
 | `"plugins"`    | `string[]`     | `[]`                                   | A list of plugins to install and activate in the environment.                                                                    |
 | `"themes"`     | `string[]`     | `[]`                                   | A list of themes to install in the environment.                                                                                  |

packages/env/lib/build-docker-compose-config.js

@@ -113,32 +113,40 @@ module.exports = function buildDockerComposeConfig( config ) {
 	const developmentPorts = `\${WP_ENV_PORT:-${ config.env.development.port }}:80`;
 	const testsPorts = `\${WP_ENV_TESTS_PORT:-${ config.env.tests.port }}:80`;
 
-	// Set the WordPress, WP-CLI, PHPUnit PHP version if defined.
+	// Set the development and CLI image's WordPress and PHP versions if defined.
 	const developmentPhpVersion = config.env.development.phpVersion
 		? config.env.development.phpVersion
 		: '';
+	const developmentSuffices = [
+		config.env.development.wpVersion,
+		developmentPhpVersion && 'php' + developmentPhpVersion,
+	].filter( Boolean );
+	// Set the WordPress development image with the WP and PHP version tags.
+	const developmentWpImage = [
+		'wordpress',
+		developmentSuffices.join( '-' ),
+	].join( ':' );
+
+	// Set the test image's WordPress and PHP versions for the if defined.
 	const testsPhpVersion = config.env.tests.phpVersion
 		? config.env.tests.phpVersion
 		: '';
-
-	// Set the WordPress images with the PHP version tag.
-	const developmentWpImage = `wordpress${
-		developmentPhpVersion ? ':php' + developmentPhpVersion : ''
-	}`;
-	const testsWpImage = `wordpress${
-		testsPhpVersion ? ':php' + testsPhpVersion : ''
-	}`;
-	// Set the WordPress CLI images with the PHP version tag.
-	const developmentWpCliImage = `wordpress:cli${
-		! developmentPhpVersion || developmentPhpVersion.length === 0
-			? ''
-			: '-php' + developmentPhpVersion
-	}`;
-	const testsWpCliImage = `wordpress:cli${
-		! testsPhpVersion || testsPhpVersion.length === 0
-			? ''
-			: '-php' + testsPhpVersion
-	}`;
+	const testsSuffices = [
+		config.env.tests.wpVersion,
+		testsPhpVersion && 'php' + testsPhpVersion,
+	].filter( Boolean );
+	// Set the WordPress tests image with the WP and PHP version tags.
+	const testsWpImage = [ 'wordpress', testsSuffices.join( '-' ) ].join( ':' );
+
+	// Set the WordPress CLI images with the WP and PHP version tags.
+	const developmentWpCliImage = [
+		'wordpress',
+		[ 'cli', ...developmentSuffices ].join( '-' ),
+	].join( ':' );
+	const testsWpCliImage = [
+		'wordpress',
+		[ 'cli', ...testsSuffices ].join( '-' ),
+	].join( ':' );
 
 	// Defaults are to use the most recent version of PHPUnit that provides
 	// support for the specified version of PHP.

packages/env/lib/config/config.js

@@ -27,6 +27,7 @@ const md5 = require( '../md5' );
  * @property {Object.<string, WPServiceConfig>} env                     Specific config for different environments.
  * @property {boolean}                          debug                   True if debug mode is enabled.
  * @property {string}                           phpVersion              Version of PHP to use in the environments, of the format 0.0.
+ * @property {string}                           wpVersion               Version of WordPress (Docker image) to use in the environments, of the format 0.0.
  */
 
 /**
@@ -71,6 +72,7 @@ module.exports = async function readConfig( configPath ) {
 	const defaultConfiguration = {
 		core: null,
 		phpVersion: null,
+		wpVersion: null,
 		plugins: [],
 		themes: [],
 		port: 8888,
@@ -261,6 +263,12 @@ function withOverrides( config ) {
 	config.env.tests.phpVersion =
 		process.env.WP_ENV_PHP_VERSION || config.env.tests.phpVersion;
 
+	// Override WordPress version with environment variable.
+	config.env.development.wpVersion =
+		process.env.WP_ENV_WP_VERSION || config.env.development.wpVersion;
+	config.env.tests.wpVersion =
+		process.env.WP_ENV_WP_VERSION || config.env.tests.wpVersion;
+
 	const updateEnvUrl = ( configKey ) => {
 		[ 'development', 'tests' ].forEach( ( envKey ) => {
 			try {

packages/env/lib/config/parse-config.js

@@ -36,6 +36,7 @@ module.exports = function parseConfig( config, options ) {
 	return {
 		port: config.port,
 		phpVersion: config.phpVersion,
+		wpVersion: config.wpVersion,
 		coreSource: includeTestsPath(
 			parseSourceString( config.core, options ),
 			options

packages/env/lib/config/test/__snapshots__/config.js.snap

@@ -26,6 +26,7 @@ Object {
       "pluginSources": Array [],
       "port": 2000,
       "themeSources": Array [],
+      "wpVersion": null,
     },
     "tests": Object {
       "config": Object {
@@ -48,6 +49,7 @@ Object {
       "pluginSources": Array [],
       "port": 1000,
       "themeSources": Array [],
+      "wpVersion": null,
     },
   },
   "name": ".",

packages/env/lib/config/validate-config.js

@@ -83,6 +83,18 @@ function validateConfig( config, envLocation ) {
 		);
 	}
 
+	if (
+		config.wpVersion &&
+		! (
+			typeof config.wpVersion === 'string' &&
+			config.wpVersion.length === 3
+		)
+	) {
+		throw new ValidationError(
+			`Invalid .wp-env.json: "${ envPrefix }wpVersion" must be a string of the format "0.0".`
+		);
+	}
+
 	return config;
 }