WPCLI

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.

Detecting requests coming from this module

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:

<?php
if (
// 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' );
}

Configuration

  • 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!

Environment configuration

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.

Example configuration

modules:
enabled:
- WPCLI
config:
WPCLI:
path: /Users/Luca/Sites/wp
throw: true
timeout: 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-value
env:
# 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'

Public API

buildFullCommand

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.

cli

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.

cliToArray

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.

cliToString

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.

dontSeeInShellOutput

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.

seeInShellOutput

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.

seeResultCodeIs

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.

seeResultCodeIsNot

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.

seeShellOutputMatches

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