Run parallel workers in throwaway Docker containers

.readme-partials/USING.md

@@ -265,6 +265,28 @@ Every worker but the first gets its own temporary directory, and with it its own
 
 Scenarios that rely on resources shared across the system, such as a fixed port or a fixed path in the system's temporary directory, are all run by the first worker, one after the other. `composer behat-rerun` re-runs exactly the scenarios that failed in the last parallel run.
 
+Set `WP_CLI_TEST_DOCKER` to run the scenarios in throwaway Docker containers instead, every worker in its own:
+```bash
+WP_CLI_TEST_DOCKER=auto WP_CLI_TEST_PARALLEL=4 composer behat
+```
+
+| `WP_CLI_TEST_DOCKER`                | Effect                                                                                           |
+|-------------------------------------|--------------------------------------------------------------------------------------------------|
+| not set (default), `0`, `no`, `off` | The scenarios run without Docker.                                                                |
+| `auto`                              | The scenarios run in containers where possible, and without Docker otherwise, which is reported. |
+| `1`, `yes`, `on`                    | The scenarios run in containers, and the run fails where that is not possible.                   |
+
+Docker is not used on Windows, when collecting code coverage, when Docker is not available, when the image cannot be built or when the database server cannot be identified.
+
+Each worker gets its own network, temporary directory and database server, of the same type and version as the one configured through the `WP_CLI_TEST_DB*` variables (or set the image through `WP_CLI_TEST_DOCKER_DB`, e.g. `mysql:8.0`). Nothing is shared between workers, so they can run any scenario. The database servers keep their data in memory. Scenarios selected by path or name run in a single container.
+
+The containers run the same PHP version as the host, unless `WP_CLI_TEST_DOCKER_PHP` sets another one:
+```bash
+WP_CLI_TEST_DOCKER=1 WP_CLI_TEST_DOCKER_PHP=7.4 WP_CLI_TEST_PARALLEL=4 composer behat
+```
+
+The project's Composer dependencies are then installed for that PHP version in a separate directory, the way CI installs them without a lock file, and refreshed once a day. Dependencies that are linked to local checkouts, as in `wp-cli/wp-cli-dev`, come from their published versions in that case, which is reported.
+
 ### Linting the feature files
 
 `composer lint-gherkin` checks `features/` with

bin/run-behat-tests

@@ -276,6 +276,45 @@ done
 # to be allowed to create, as set up by "composer prepare-tests".
 PARALLEL="${WP_CLI_TEST_PARALLEL-}"
 
+# With WP_CLI_TEST_DOCKER set, the scenarios run in throwaway containers instead, every worker in
+# its own, with a database server of the same type and version, so they share nothing.
+# "auto" runs them without Docker where it cannot be used, "1" (or "yes", "true", "on") fails instead.
+case "${WP_CLI_TEST_DOCKER-}" in
+	""|0|no|false|off) DOCKER="";;
+	auto) DOCKER="auto";;
+	1|yes|true|on) DOCKER="force";;
+	*)
+		echo "Warning: WP_CLI_TEST_DOCKER is neither \"auto\" nor a yes or no, running the scenarios without Docker." >&2
+		DOCKER="";;
+esac
+
+without_docker() {
+	if [ "${DOCKER}" = "force" ]; then
+		echo "Error: $1 Set WP_CLI_TEST_DOCKER to \"auto\" to run the scenarios without Docker in that case." >&2
+		exit 1
+	fi
+	echo "$1 Running the scenarios without Docker." >&2
+	DOCKER=""
+}
+
+case "$(uname -s)" in
+	MINGW*|MSYS*|CYGWIN*)
+		PARALLEL=""
+		if [ -n "${DOCKER}" ]; then
+			without_docker "The scenarios cannot run in Docker containers on Windows."
+		fi;;
+esac
+
+if [ -n "${DOCKER}" ]; then
+	if ! command -v docker > /dev/null 2>&1 || ! docker info > /dev/null 2>&1; then
+		without_docker "Docker is not available."
+	elif [[ "${WP_CLI_TEST_COVERAGE}" == "true" ]]; then
+		without_docker "Code coverage cannot be collected in Docker containers."
+	fi
+fi
+
+export WP_CLI_TEST_DOCKER="${DOCKER}"
+
 # A rerun after a parallel run covers exactly the scenarios that failed in it, which only the
 # parallel runner knows, whether or not WP_CLI_TEST_PARALLEL is set for the rerun as well.
 for arg in "$@"; do
@@ -284,10 +323,10 @@ for arg in "$@"; do
 	fi
 done
 
-case "$(uname -s)" in
-	MINGW*|MSYS*|CYGWIN*)
-		PARALLEL="";;
-esac
+if [ -n "${DOCKER}" ]; then
+	exec php "$WP_CLI_TESTS_ROOT"/utils/behat-parallel.php "${PARALLEL:-1}" --snippets-for="WP_CLI\Tests\Context\FeatureContext" "${FORMAT_ARGS[@]}" "$BEHAT_TAGS" --strict "${BEHAT_EXTRA_ARGS[@]}" -- "$@"
+fi
+
 if [ -n "${PARALLEL}" ] && [ "${PARALLEL}" != "1" ]; then
 	if ! is_numeric "${PARALLEL}"; then
 		echo "Warning: WP_CLI_TEST_PARALLEL is not a number of workers, running the scenarios one after the other." >&2