This module should be used in acceptance and functional tests to setup, or verify, tests pre and post conditions. This module allows invoking any supported WP-CLI command, refer to the official site for more information. The module will use its own version of wp-cli, not the one installed in the machine running the tests to grant isolation from local settings.
When it runs this module will set the WPBROWSER_HOST_REQUEST
environment variable.
You can detect and use that information to, as an example, use the correct database in your test site wp-config.php
file:
<?phpif (// Custom header.isset( $_SERVER['HTTP_X_TESTING'] )// Custom user agent.|| ( isset( $_SERVER['HTTP_USER_AGENT'] ) && $_SERVER['HTTP_USER_AGENT'] === 'wp-browser' )// The env var set by the WPClIr or WordPress modules.|| getenv( 'WPBROWSER_HOST_REQUEST' )) {// Use the test database if the request comes from a test.define( 'DB_NAME', 'wordpress_test' );} else {// Else use the default one.define( 'DB_NAME', 'wordpress' );}
path
required - the absolute, or relative, path to the WordPress root folder. This will be mapped to the --path
argument of the wp-cli binary.
throw
- defaults to true
to throw an exception when a wp-cli command does not return an exit status of 0
; if set to false
then the exit status of the commands will be returned as is.
timeout
- defaults to 60
(seconds) to set each process execution timeout to a certain value; set to null
, false
or 0
to disable timeout completely.
Additionally the module configuration will forward any configuration parameter to wp-cli
as a flag or option. In the example configuration below the allow-root
flag and the some-option
option will be passed to wp-cli
directly and prepended to the command as global options.
Note: these extract configuration flags and options will be prepended to all commands executed by wp-cli!
The wp-cli binary supports a set of enviroment variables to modify its behavior.
These environment variables can be set on the commands ran by the WPCLI
module using the optional env
array in the module configuration.
The example configuration below shows all of them with some example values.
Most of the times you won't need any of these, but they are there for more fine-grained control over the module operations.
The module is not validating the environment variables in any way! Those values will be evaluated by wp-cli at runtime and might generate errors if not correctly configured.
modules:enabled:- WPCLIconfig:WPCLI:path: /Users/Luca/Sites/wpthrow: truetimeout: 60# This will be prepended to the command, `wp --allow-root <command>`.allow-root: true# This will be prepended to the command, `wp --some-option=some-value <command>`.some-option: some-valueenv:# Any one of these, if provided, will be set as environment variable for the the cli command process.# See https://make.wordpress.org/cli/handbook/config/#environment-variables for information.# Equivalent to `WP_CLI_STRICT_ARGS_MODE=1 wp <command>'.strict-args: true# Equivalent to `WP_CLI_CACHE_DIR=/tmp/wp-cli-cache wp <command>'.cache-dir: '/tmp/wp-cli-cache'# Equivalent to `WP_CLI_CONFIG_PATH=/app/public wp <command>'.config-path: '/app/public'# Equivalent to `WP_CLI_CUSTOM_SHELL=/bin/zsh wp <command>'.custom-shell: '/bin/zsh'# Equivalent to `WP_CLI_DISABLE_AUTO_CHECK_UPDATE=1 wp <command>'.disable-auto-update: true# Equivalent to `WP_CLI_PACKAGES_DIR=/wp-cli/packages wp <command>'.packages-dir: '/wp-cli/packages'# Equivalent to `WP_CLI_PHP=/usr/local/bin/php/7.2/php wp <command>'.php: '/usr/local/bin/php/7.2/php'# Equivalent to `WP_CLI_PHP_ARGS='foo=bar some=23' wp <command>'.php-args: 'foo=bar some=23'
cli​
cliToArray​
cliToString​
Builds the full command to run including the PHP binary and the wp-cli boot file path.
// This method is defined in the WithWpCli trait.// Set the wp-cli path, `$this` is a test case.$this->setUpWpCli( '/var/www/html' );// Builds the full wp-cli command, including the `path` variable.$fullCommand = $this->buildFullCommand(['core', 'version']);// The full command can then be used to run it with another process handler.$wpCliProcess = new \Symfony\Component\Process\Process($fullCommand);$wpCliProcess->run();
Parameters
array/string
$command - The command to run.
Executes a wp-cli command targeting the test WordPress installation. For back-compatibility purposes you can still pass the commandline as a string, but the array format is the preferred and supported method.
// Activate a plugin via wp-cli in the test WordPress site.$I->cli(['plugin', 'activate', 'my-plugin']);// Change a user password.$I->cli(['user', 'update', 'luca', '--user_pass=newpassword']);
Parameters
string/string/array
$userCommand - The string of command and parameters as it would be passed to wp-cli minus wp
.
Returns the output of a wp-cli command as an array optionally allowing a callback to process the output. wp
. For back-compatibility purposes you can still pass the commandline as a string, but the array format is the preferred and supported method.
// Return a list of inactive themes, like ['twentyfourteen', 'twentyfifteen'].$inactiveThemes = $I->cliToArray(['theme', 'list', '--status=inactive', '--field=name']);// Get the list of installed plugins and only keep the ones starting with "foo".$fooPlugins = $I->cliToArray(['plugin', 'list', '--field=name'], function($output){return array_filter(explode(PHP_EOL, $output), function($name){return strpos(trim($name), 'foo') === 0;});});
Parameters
string/string/array
$userCommand - The string of command and parameters as it would be passed to wp-cli minus
\callable
$splitCallback - An optional callback function in charge of splitting the results array.
Returns the output of a wp-cli command as a string. For back-compatibility purposes you can still pass the commandline as a string, but the array format is the preferred and supported method.
// Return the current site administrator email, using string command format.$adminEmail = $I->cliToString('option get admin_email');// Get the list of active plugins in JSON format.$activePlugins = $I->cliToString(['wp','option','get','active_plugins','--format=json']);
Parameters
string/array
$userCommand - The string of command and parameters as it would be passed to wp-cli minus wp
.
Checks that output from last command doesn't contain text.
// Return the current site administrator email, using string command format.$I->cli('plugin list --status=active');$I->dontSeeInShellOutput('my-inactive/plugin.php');
Parameters
string
$text - The text to assert is not in the output.
Checks that output from last command contains text.
// Return the current site administrator email, using string command format.$I->cli('option get admin_email');
Parameters
string
$text - The text to assert is in the output.
Checks the result code from the last command.
// Return the current site administrator email, using string command format.$I->cli('option get admin_email');$I->seeResultCodeIs(0);
Parameters
int
$code - The desired result code.
Checks the result code from the last command.
// Return the current site administrator email, using string command format.$I->cli('invalid command');$I->seeResultCodeIsNot(0);
Parameters
int
$code - The result code the command should not have exited with.
Checks that output from the last command matches a given regular expression.
// Return the current site administrator email, using string command format.$I->cli('option get admin_email');
Parameters
string
$regex - The regex pattern, including delimiters, to assert the output matches against.
This class extends \Codeception\Module