WP_Mock is an API mocking framework, built and maintained by 10up for the purpose of making it possible to properly unit test within WordPress.
First, add WP Mock as a dev-dependency with Composer:
composer require --dev 10up/wp_mock:dev-masterThen, make sure your bootstrap file is loading the composer autoloader:
require_once 'vendor/autoload.php';Finally, register calls inside your test class to instantiate and clean up the WP_Mock object:
class MyTestClass extends PHPUnit_Framework_TestCase {
public function setUp() {
\WP_Mock::setUp();
}
public function tearDown() {
\WP_Mock::tearDown();
}
}Write your tests as you normally would. If you desire specific responses from WordPress API calls, wire those specifically.
class MyTestClass extends PHPUnit_Framework_TestCase {
public function setUp() {
\WP_Mock::setUp();
}
public function tearDown() {
\WP_Mock::tearDown();
}
/**
* Assume that my_permalink_function() is meant to do all of the following:
* - Run the given post ID through absint()
* - Call get_permalink() on the $post_id
* - Pass the permalink through the 'special_filter' filter
* - Trigger the 'special_action' WordPress action
*/
public function test_my_permalink_function() {
\WP_Mock::wpFunction( 'get_permalink', array(
'args' => 42,
'times' => 1,
'return' => 'http://example.com/foo'
) );
\WP_Mock::wpPassthruFunction( 'absint', array( 'times' => 1 ) );
\WP_Mock::onFilter( 'special_filter' )
->with( 'http://example.com/foo' )
->reply( 'https://example.com/bar' );
\WP_Mock::expectAction( 'special_action', 'https://example.com/bar' );
$result = my_permalink_function( 42 );
$this->assertEquals( 'https://example.com/bar', $result );
}
}The function being described by our tests would look something like this:
/**
* Get a post's permalink, then run it through special filters and trigger
* the 'special_action' action hook.
*
* @param int $post_id The post ID being linked to.
* @return str|bool The permalink or a boolean false if $post_id does
* not exist.
*/
function my_permalink_function( $post_id ) {
$permalink = get_permalink( absint( $post_id ) );
$permalink = apply_filters( 'special_filter', $permalink );
do_action( 'special_action', $permalink );
return $permalink;
}Ideally, a unit test will not depend on WordPress being loaded in order to test our code. By constructing mocks, it's possible to simulate WordPress core functionality by defining their expected arguments, responses, the number of times they are called, and more. In WP_Mock, this is done via the \WP_Mock::wpFunction() method:
public function test_uses_get_post() {
global $post;
$post = new \stdClass;
$post->ID = 42;
$post->special_meta = '<p>I am on the end</p>';
\WP_Mock::wpFunction( 'get_post', array(
'times' => 1,
'args' => array( $post->ID ),
'return' => $post,
) );
/*
* Let's say our function gets the post and appends a value stored in
* 'special_meta' to the content.
*/
$results = special_the_content( '<p>Some content</p>' );
/*
* In addition to failing if this assertion is false, the test will fail
* if get_post is not called with the arguments above.
*/
$this->assertEquals( '<p>Some content</p><p>I am on the end</p>', $results );
}In the example above, we're creating a simple \stdClass to represent a response from get_post(), setting the ID and special_meta properties. WP_Mock is expecting get_post() to be called exactly once, with a single argument of '42', and for the function to return our $post object.
With our expectations set, we call special_the_content(), the function we're testing, then asserting that what we get back from it is equal to <p>Some content</p><p>I am on the end</p>, which proves that special_the_content() appended $post->special_meta to <p>Some content</p>.
Calling \WP_Mock::wpFunction() will dynamically define the function for you if necessary, which means changes the internal WP_Mock API shouldn't break your mocks. If you really want to define your own function mocks, they should always end with this line:
return \WP_Mock\Handler::handle_function( __FUNCTION__, func_get_args() );\WP_Mock::wpFunction() accepts an associative array of arguments for its second parameter:
Sets expectations about what the arguments passed to the function should be. This value should always be an array with the arguments in order and, like with return, if you use a \Closure, its return value will be used to validate the argument expectations. You can also indicate that the argument can be any value of any type by using '*'.
WP_Mock has several helper functions to make this feature more flexible. The are static methods on the \WP_Mock\Functions class. They are:
Functions::type( $type ): Expects an argument of a certain type. This can be any core PHP data type (string,int,resource,callable, etc.) or any class or interface name.Functions::anyOf( $values ): Expects the argument to be any value in the$valuesarray.
In the following example, we're expecting get_post_meta() twice: once each for some_meta_key and another_meta_key, where an integer (in this case, a post ID) is the first argument, the meta key is the second, and a boolean TRUE is the third.
\WP_Mock::wpFunction( 'get_post_meta', array(
'times' => 1,
'args' => array( \WP_Mock\Functions::type( 'int' ), 'some_meta_key', true )
) );
\WP_Mock::wpFunction( 'get_post_meta', array(
'times' => 1,
'args' => array( \WP_Mock\Functions::type( 'int' ), 'another_meta_key', true )
) );Declares how many times the given function should be called. For an exact number of calls, use a non-negative, numeric value (e.g. 3). If the function should be called a minimum number of times, append a plus-sign (+, e.g. 7+ for seven or more calls). Conversely, if a mocked function should have a maximum number of invocations, append a minus-sign (-) to the argument (e.g. 7- for seven or fewer times).
You may also choose to specify a range, e.g. 3-6 would translate to "this function should be called between three and six times".
The default value for times is 0+, meaning the function should be called any number of times.
Defines the value (if any) that the function should return. If you pass a \Closure as the return value, the function will return whatever the Closure's return value is.
Set an array of values that should be returned with each subsequent call, useful if if your function will be called multiple times in the test but needs to return different values.
Note: Setting this value overrides whatever may be set return.
\WP_Mock::wpFunction( 'is_single', array(
'return_in_order' => array( true, false )
) );
$this->assertTrue( is_single() );
$this->assertFalse( is_single() );
$this->assertFalse( is_single() ); // All subsequent calls will use the last defined return valueUse this to specify that the function should return one of its arguments. return_arg should be the position of the argument in the arguments array, so 0 for the first argument, 1 for the second, etc. You can also set this to true, which is equivalent to 0. This will override both return and return_in_order.
It's not uncommon for tests to need to declare "passthrough/passthru" functions: empty functions that just return whatever they're passed (remember: you're testing your code, not the framework). In these situations you can use \WP_Mock::wpPassthruFunction( 'function_name' ), which is equivalent to the following:
\WP_Mock::wpFunction( 'function_name', array(
'return_arg' => 0
) );You can still test things like invocation count by passing the times argument in the second parameter, just like \WP_Mock::wpFunction().
The hooks and filters of the WordPress Plugin API are common (and preferred) entry points for third-party scripts, and WP_Mock makes it easy to test that these are being registered and executed within your code.
Rather than attempting to mock add_action() or add_filter(), WP_Mock has built-in support for both of these functions: instead, use \WP_Mock::expectActionAdded() and \WP_Mock::expectFilterAdded() (respectively). In the following example, our test_special_function() test will fail if special_function() doesn't call add_action( 'save_post', 'special_save_post', 10, 2 ) and add_filter( 'the_content', 'special_the_content' ):
public function test_special_function() {
\WP_Mock::expectActionAdded( 'save_post', 'special_save_post', 10, 2 );
\WP_Mock::expectFilterAdded( 'the_content', 'special_the_content' );
special_function();
}It's important to note that the $priority and $parameter_count arguments (parameters 3 and 4 for both add_action() and add_filter()) are significant. If special_function() were to call add_action( 'save_post', 'special_save_post', 99, 3 ) instead of the expected add_action( 'save_post', 'special_save_post', 10, 2 ), our test would fail.
Now that we're testing whether or not we're adding actions and/or filters, the next step is to ensure our code is calling those hooks when expected.
For actions, we'll want to listen for do_action() to be called for our action name, so we'll use \WP_Mock::expectAction():
function test_action_calling_function () {
\WP_Mock::expectAction( 'my_action' );
action_calling_function();
}This test will fail if action_calling_function() doesn't call do_action( 'my_action' ). In situations where your code needs to trigger actions, this assertion makes sure the appropriate hooks are being triggered.
For filters, we can inject our own response to apply_filters() using \WP_Mock::onFilter():
public function filter_content() {
return apply_filters( 'custom_content_filter', 'This is unfiltered' );
}
public function test_filter_content() {
\WP_Mock::onFilter( 'custom_content_filter' )
->with( 'This is unfiltered' )
->reply( 'This is filtered' );
$response = $this->filter_content();
$this->assertEquals( 'This is filtered', $response );
}Thanks so much for being interested in contributing! Please read over our guidelines before you get started.