Env: Download WordPress PHPUnit Into Container

packages/env/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Breaking Changes
+-   Removed the `WP_PHPUNIT__TESTS_CONFIG` environment variable from the `phpunit` container. **This removes automatic support for `wp-phpunit/wp-phpunit`**.
+-   Removed the generated `/var/www/html/phpunit-wp-config.php` file from the environment.
+
+### Enhancement
+-   Read WordPress' version and include the correspond PHPUnit test files in the environment.
+-   Set the `WP_TESTS_DIR` environment variable in all containers to point at the PHPUnit test files.
+
 ## 4.8.0 (2022-06-01)
 ### Enhancement
 -   Removed the need for quotation marks when passing options to `wp-env run`.

packages/env/README.md

@@ -188,6 +188,20 @@ wp-env start --debug
 	...
 ```
 
+## Using included WordPress PHPUnit test files
+
+Out of the box `wp-env` includes the [WordPress' PHPUnit test files](https://develop.svn.wordpress.org/trunk/tests/phpunit/) corresponding to the version of WordPress installed. There is an environment variable, `WP_TESTS_DIR`, which points to the location of these files within each container. By including these files in the environment, we remove the need for you to use a package or install and mount them yourself.
+
+### Custom `wp-tests-config.php` file
+
+WordPress provides a `WP_TESTS_CONFIG_FILE_PATH` constant that you can use to change the `wp-config.php` file used for testing. Set this to a desired path in your `bootstrap.php` file and the file you've chosen will be used instead of the one included in the environment.
+
+### Using `wp-phpunit/wp-phpunit`
+
+By including these test files, we remove the need for using packages like `wp-phpunit/wp-phpunit`. One of the issues with the package approach is that the version of the test files it includes may not correspond to the version of WordPress in the container. We solve this by instead reading the version of WordPress installed and downloading the files _for that version_.
+
+However, if you would still like to use a package, you can do so by not using the `WP_TESTS_DIR` environment variable in your `bootstrap.php`. If this is not an option, you can also set the environment variable to an empty string in your `phpunit.xml` file. You will also need to set the `WP_PHPUNIT__TESTS_CONFIG` environment variable to a custom `wp-tests-config.php` file for your test suite.
+
 ## Using Xdebug
 
 Xdebug is installed in the wp-env environment, but it is turned off by default. To enable Xdebug, you can use the `--xdebug` flag with the `wp-env start` command. Here is a reference to how the flag works:

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

@@ -19,13 +19,18 @@ const { dbEnv } = require( './config' );
 /**
  * Gets the volume mounts for an individual service.
  *
- * @param {WPServiceConfig} config           The service config to get the mounts from.
- * @param {string}          wordpressDefault The default internal path for the WordPress
- *                                           source code (such as tests-wordpress).
+ * @param {string}          workDirectoryPath The working directory for wp-env.
+ * @param {WPServiceConfig} config            The service config to get the mounts from.
+ * @param {string}          wordpressDefault  The default internal path for the WordPress
+ *                                            source code (such as tests-wordpress).
  *
  * @return {string[]} An array of volumes to mount in string format.
  */
-function getMounts( config, wordpressDefault = 'wordpress' ) {
+function getMounts(
+	workDirectoryPath,
+	config,
+	wordpressDefault = 'wordpress'
+) {
 	// Top-level WordPress directory mounts (like wp-content/themes)
 	const directoryMounts = Object.entries( config.mappings ).map(
 		( [ wpDir, source ] ) => `${ source.path }:/var/www/html/${ wpDir }`
@@ -45,9 +50,19 @@ function getMounts( config, wordpressDefault = 'wordpress' ) {
 		config.coreSource ? config.coreSource.path : wordpressDefault
 	}:/var/www/html`;
 
+	const corePHPUnitMount = `${ path.join(
+		workDirectoryPath,
+		wordpressDefault === 'wordpress'
+			? 'WordPress-PHPUnit'
+			: 'tests-WordPress-PHPUnit',
+		'tests',
+		'phpunit'
+	) }:/wordpress-phpunit`;
+
 	return [
 		...new Set( [
 			coreMount,
+			corePHPUnitMount,
 			...directoryMounts,
 			...pluginMounts,
 			...themeMounts,
@@ -64,8 +79,15 @@ function getMounts( config, wordpressDefault = 'wordpress' ) {
  * @return {Object} A docker-compose config object, ready to serialize into YAML.
  */
 module.exports = function buildDockerComposeConfig( config ) {
-	const developmentMounts = getMounts( config.env.development );
-	const testsMounts = getMounts( config.env.tests, 'tests-wordpress' );
+	const developmentMounts = getMounts(
+		config.workDirectoryPath,
+		config.env.development
+	);
+	const testsMounts = getMounts(
+		config.workDirectoryPath,
+		config.env.tests,
+		'tests-wordpress'
+	);
 
 	// When both tests and development reference the same WP source, we need to
 	// ensure that tests pulls from a copy of the files so that it maintains
@@ -208,6 +230,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 				environment: {
 					...dbEnv.credentials,
 					...dbEnv.development,
+					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
 				volumes: developmentMounts,
 			},
@@ -218,6 +241,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 				environment: {
 					...dbEnv.credentials,
 					...dbEnv.tests,
+					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
 				volumes: testsMounts,
 			},
@@ -229,6 +253,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 				environment: {
 					...dbEnv.credentials,
 					...dbEnv.development,
+					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
 			},
 			'tests-cli': {
@@ -239,6 +264,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 				environment: {
 					...dbEnv.credentials,
 					...dbEnv.tests,
+					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
 			},
 			composer: {
@@ -256,8 +282,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 				],
 				environment: {
 					LOCAL_DIR: 'html',
-					WP_PHPUNIT__TESTS_CONFIG:
-						'/var/www/html/phpunit-wp-config.php',
+					WP_TESTS_DIR: '/wordpress-phpunit',
 					...dbEnv.credentials,
 					...dbEnv.tests,
 				},

packages/env/lib/commands/run.js

@@ -9,7 +9,7 @@ const { spawn } = require( 'child_process' );
 const initConfig = require( '../init-config' );
 
 /**
- * @typedef {import('../config').Config} Config
+ * @typedef {import('../config').WPConfig} WPConfig
  */
 
 /**
@@ -42,11 +42,11 @@ module.exports = async function run( { container, command, spinner, debug } ) {
 /**
  * Runs an arbitrary command on the given Docker container.
  *
- * @param {Object} options
- * @param {string} options.container The Docker container to run the command on.
- * @param {string} options.command   The command to run.
- * @param {Config} options.config    The wp-env configuration.
- * @param {Object} options.spinner   A CLI spinner which indicates progress.
+ * @param {Object}   options
+ * @param {string}   options.container The Docker container to run the command on.
+ * @param {string}   options.command   The command to run.
+ * @param {WPConfig} options.config    The wp-env configuration.
+ * @param {Object}   options.spinner   A CLI spinner which indicates progress.
  */
 function spawnCommandDirectly( { container, command, config, spinner } ) {
 	const composeCommand = [

packages/env/lib/commands/start.js

@@ -21,16 +21,18 @@ const retry = require( '../retry' );
 const stop = require( './stop' );
 const initConfig = require( '../init-config' );
 const downloadSources = require( '../download-sources' );
+const downloadWPPHPUnit = require( '../download-wp-phpunit' );
 const {
 	checkDatabaseConnection,
 	configureWordPress,
 	setupWordPressDirectories,
+	readWordPressVersion,
 } = require( '../wordpress' );
 const { didCacheChange, setCache } = require( '../cache' );
 const md5 = require( '../md5' );
 
 /**
- * @typedef {import('../config').Config} Config
+ * @typedef {import('../config').WPConfig} WPConfig
  */
 const CONFIG_CACHE_KEY = 'config_checksum';
 
@@ -127,7 +129,25 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 	] );
 
 	if ( shouldConfigureWp ) {
+		spinner.text = 'Setting up WordPress directories';
+
 		await setupWordPressDirectories( config );
+
+		// Use the WordPress versions to download the PHPUnit suite.
+		const wpVersions = await Promise.all( [
+			readWordPressVersion(
+				config.env.development.coreSource,
+				spinner,
+				debug
+			),
+			readWordPressVersion( config.env.tests.coreSource, spinner, debug ),
+		] );
+		await downloadWPPHPUnit(
+			config,
+			{ development: wpVersions[ 0 ], tests: wpVersions[ 1 ] },
+			spinner,
+			debug
+		);
 	}
 
 	spinner.text = 'Starting WordPress.';

packages/env/lib/download-sources.js

@@ -16,16 +16,16 @@ const extractZip = util.promisify( require( 'extract-zip' ) );
 const rimraf = util.promisify( require( 'rimraf' ) );
 
 /**
- * @typedef {import('./config').Config} Config
+ * @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 {Config} config  The wp-env configuration object.
- * @param {Object} spinner The spinner object to show progress.
+ * @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 ) {

packages/env/lib/download-wp-phpunit.js

@@ -0,0 +1,140 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const SimpleGit = require( 'simple-git' );
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * @typedef {import('./config').WPConfig} WPConfig
+ */
+
+/**
+ * Downloads the WordPress PHPUnit files for each environment into the appropriate directories.
+ *
+ * @param {WPConfig} config     The wp-env config object.
+ * @param {Object}   wpVersions The WordPress versions for each environment.
+ * @param {Object}   spinner    The spinner object to show progress.
+ * @param {boolean}  debug      Indicates whether or not debug mode is active.
+ * @return {Promise} Returns a promise which resolves when the downloads finish.
+ */
+module.exports = function downloadWPPHPUnit(
+	config,
+	wpVersions,
+	spinner,
+	debug
+) {
+	const progresses = {};
+	const getProgressSetter = ( id ) => ( progress ) => {
+		progresses[ id ] = progress;
+		spinner.text =
+			'Downloading WordPress PHPUnit Suite.\n' +
+			Object.entries( progresses )
+				.map(
+					( [ key, value ] ) =>
+						`  - ${ key }: ${ ( value * 100 ).toFixed( 0 ) }/100%`
+				)
+				.join( '\n' );
+	};
+
+	const promises = [];
+	for ( const env in config.env ) {
+		const wpVersion = wpVersions[ env ] ? wpVersions[ env ] : null;
+		const directory = path.join(
+			config.workDirectoryPath,
+			env === 'development'
+				? 'WordPress-PHPUnit'
+				: 'tests-WordPress-PHPUnit'
+		);
+		promises.push(
+			downloadTestSuite( directory, wpVersion, {
+				onProgress: getProgressSetter,
+				spinner,
+				debug,
+			} )
+		);
+	}
+
+	return Promise.all( promises );
+};
+
+/**
+ * Downloads the PHPUnit tests for a given WordPress version into the appropriate directory.
+ *
+ * @param {string}   directory          The directory to place the PHPUnit tests in.
+ * @param {string}   wpVersion          The version of WordPress to install PHPUnit tests for. Trunk when empty.
+ * @param {Object}   options
+ * @param {Function} options.onProgress A function called with download progress. Will be invoked with one argument: a number that ranges from 0 to 1 which indicates current download progress for this source.
+ * @param {Object}   options.spinner    A CLI spinner which indicates progress.
+ * @param {boolean}  options.debug      True if debug mode is enabled.
+ */
+async function downloadTestSuite(
+	directory,
+	wpVersion,
+	{ onProgress, spinner, debug }
+) {
+	const log = debug
+		? ( message ) => {
+				spinner.info( `SimpleGit: ${ message }` );
+				spinner.start();
+		  }
+		: () => {};
+	onProgress( 0 );
+
+	const progressHandler = ( { progress } ) => {
+		onProgress( progress / 100 );
+	};
+
+	// Make sure that the version is in X.X.X format. This is required
+	// because WordPress/wordpress-develop uses X.X.X tags but
+	// WordPress uses X.X for non-patch releases.
+	if ( wpVersion && wpVersion.match( /^[0-9]+.[0-9]+$/ ) ) {
+		wpVersion += '.0';
+	}
+
+	log( 'Cloning or getting the PHPUnit suite from GitHub.' );
+	const git = SimpleGit( { progress: progressHandler } );
+
+	const isRepo =
+		fs.existsSync( directory ) &&
+		( await git.cwd( directory ).checkIsRepo( 'root' ) );
+
+	if ( isRepo ) {
+		log( 'Repo already exists, using it.' );
+	} else {
+		await git.clone(
+			'https://github.com/WordPress/wordpress-develop.git',
+			directory,
+			{
+				'--depth': '1',
+				'--no-checkout': null,
+			}
+		);
+		await git.cwd( directory );
+
+		// We use a sparse checkout to minimize the amount of data we need to download.
+		log( 'Enabling sparse checkout.' );
+		await git.raw( 'sparse-checkout', 'set', '--cone', 'tests/phpunit' );
+	}
+
+	// Figure out the ref that we need to checkout to get the correct version of the PHPUnit library.
+	// Alpha, Beta, and RC versions are bleeding edge and should pull from trunk.
+	let ref;
+	const fetchRaw = [];
+	if ( ! wpVersion || wpVersion.match( /-(?:alpha|beta|rc)/ ) ) {
+		ref = 'trunk';
+		fetchRaw.push( 'fetch', 'origin', ref, '--depth', '1' );
+	} else {
+		ref = `tags/${ wpVersion }`;
+		fetchRaw.push( 'fetch', 'origin', 'tag', wpVersion, '--depth', '1' );
+	}
+
+	log( `Fetching ${ ref }.` );
+	await git.raw( fetchRaw );
+
+	log( `Checking out ${ ref }.` );
+	await git.checkout( ref );
+
+	onProgress( 1 );
+}