Add WP CLI helper for codeception

docs/testing-with-codeception.md

@@ -592,7 +592,29 @@ This module is typically used in acceptance and functional tests to invoke WP-CL
 
 ### Altis helpers
 
-Altis extends Codeception/wp-browser with its own helpers. Check out the `tests/_helpers` directory within the `dev-tools` package to check out existing helpers and new available functionality.
+Altis extends Codeception with its own helpers. These can be found in the `tests/_support/Helper` directory within the `vendor/altis/dev-tools` package.
+
+All helpers are under the `\Helper` namespace.
+
+#### `Helper\WPCLI`
+
+This helper provides a way to run WP CLI commands using the PHP Server's built in WP CLI package. This means you do not need to install any additional command packages to use them, and is useful if you are not testing CLI commands specifically but need to run a background cron task during a test for example. The following methods to the `$I` class:
+
+- `$I->wpCli( string $command )`: Run any WP CLI command, minus the `wp`
+- `$I->grabLastWpCliShellOutput()`: Retrieve the output from the previous call to `$I->wpCli()`
+- `$I->grabLastWpCliExitCode()`: Retrieve the exit code from the previous call to `$I->wpCli()`
+- `$I->wpCliToString( string $command )`: Run a command and return the output as a string
+- `$I->wpCliToArray( string $command )`: Run a command and return the output as an array, split on newlines.
+
+To use the helper, update your suite's YAML configuration, for example:
+
+```yml
+actor: AcceptanceTester
+modules:
+    enabled:
+        - WPBrowser
+        - \Helper\WPCLI
+```
 
 ## Scaffolding
 

tests/_support/Helper/WPCLI.php

@@ -0,0 +1,80 @@
+<?php
+namespace Helper;
+
+// here you can define custom actions
+// all public methods declared in helper class will be available in $I
+
+use \Codeception\Module;
+
+class WPCLI extends Module {
+
+	/**
+	 * Previous shell output.
+	 *
+	 * @var string|array
+	 */
+	protected $shell_output;
+
+	/**
+	 * Previous shell exit code.
+	 *
+	 * @var int
+	 */
+	protected $shell_exit_code;
+
+	/**
+	 * Use the full WP CLI to run a command.
+	 *
+	 * @param string $command Command to run minus 'wp'.
+	 * @return void
+	 */
+	public function wpCli( string $command = '' ) {
+		unset( $this->shell_output, $this->shell_exit_code );
+		// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.system_calls_exec
+		exec( sprintf(
+			'WPBROWSER_HOST_REQUEST=1 wp --url=%s %s',
+			getenv( 'TEST_SITE_WP_DOMAIN' ),
+			$command
+		), $this->shell_output, $this->shell_exit_code );
+	}
+
+	/**
+	 * Use the full WP CLI to run a command and get the output.
+	 *
+	 * @param string $command Command to run minus 'wp'.
+	 * @return string
+	 */
+	public function wpCliToString( string $command = '' ) : string {
+		$this->wpCli( $command );
+		return implode( "\n", (array) $this->shell_output );
+	}
+
+	/**
+	 * Use the full WP CLI to run a command and get the output as an array.
+	 *
+	 * @param string $command Command to run minus 'wp'.
+	 * @return array
+	 */
+	public function wpCliToArray( string $command = '' ) : array {
+		$this->wpCli( $command );
+		return (array) $this->shell_output;
+	}
+
+	/**
+	 * Return the last exit code from WP CLI.
+	 *
+	 * @return integer
+	 */
+	public function grabLastWpCliExitCode() : int {
+		return (int) $this->shell_exit_code;
+	}
+
+	/**
+	 * Return the last output from WP CLI.
+	 *
+	 * @return string
+	 */
+	public function grabLastWpCliShellOutput() : string {
+		return implode( "\n", (array) $this->shell_output );
+	}
+}