The other day I was refactoring some code for an Ajax callback in one of my plugins. I was dreading having to manually test that the changes I was making didn’t break anything, when I had an idea. “Why don’t I have unit tests for this?”, I though to myself. Before I started trying to mock Ajax requests myself, I thought I’d ask Google what was already out there. As it turns out, the WordPress unit test framework already provides a testcase specifically for testing Ajax callbacks. Who knew? Obviously, the developers did, but I hadn’t thought much about it before, except that each time you run the WP unit tests, you get a message that it the Ajax unit tests aren’t being run.

While I found this testcase in the WordPress PHPUnit test source code, what I didn’t find was any tutorials on how it works. So, I just used WP’s AJAX unit tests as an example. Its pretty simple actually.

The WP_Ajax_UnitTestCase

If you’re familiar with plugin unit testing, you know that your testcases need to extend the WP_UnitTestCase class to leverage the full power of the WordPress testing framework. Well, for Ajax tests, its the same thing, only you need to extend a child of WP_UnitTestCase: WP_Ajax_UnitTestCase. This testcase provides a few methods that make the Ajax unit tests simpler.

The most important method is of course the one that actually mocks the Ajax request: _handleAjax(). It takes just one parameter; the name of the Ajax action:

$this->_handleAjax( 'my_ajax_action' );

Setting up for the test

Of course, before you run the Ajax handler, you will need to set up for the test. The first thing you need to do is set up the $_POST data. You need to mock up the $_POSTed data, and then later we’ll check that we get the expected result.

$_POST['_nonce'] = wp_create_nonce( 'my_nonce' );
$_POST['other_data'] = 'something';

Setting the expected exception

The test is performed by running the 'wp_ajax_*' action, and thus invoking the callback. (No request is actually made.) When the Ajax callback function runs, it should finish by calling die() or exit(). Well, actually, it will need to be using wp_die(), because if you call die() you will kill the tests. Lesson: in WP Ajax callbacks, you should use wp_die(). Fortunately, I already was in the callbacks that I was testing, so I was good to go.

Now, when wp_die() gets called, the testcase catches it and prevents it from actually killing the execution of the script. Instead, it throws an exception. The testcase uses two different exceptions, and which one gets thrown depends on whether there was any output from callback (this is caught with a buffer). If there was output, a WPAjaxDieStopException is thrown. Otherwise, a WPAjaxDieContinueException is thrown. These need to be caught. One way that this is done is using the setExpectedException() method provided by PHPUnit.

If, for example, you are expecting the callback to exit without any output, you would do this:

$this->setExpectedException( 'WPAjaxDieStopException' );
$this->_handleAjax( 'my_ajax_action' );

If you need to run some assertions afterward, you’ll need to catch the exception manually instead. For example, your Ajax callback may be supposed to save some data to the database, and you’ll want to check that the data was actually saved.

try {
	$this->_handleAjax( 'my_ajax_action' );
} catch ( WPAjaxDieStopException $e ) {
	// We expected this, do nothing.
}

$this->assertEquals( 'yes', get_option( 'some_option' ) );

Checking for the Correct Output

If your Ajax function outputs some data, you will probably want to check that the expected data gets output. If you are sending a simple response code with wp_die(), you’ll probably want to check that the expected value was output. The message passed to wp_die() is the message of the exception that gets thrown. So one way to check for this is when you set the expected exception:

$this->setExpectedException( 'WPAjaxDieStopException', '1' );

In this case we are expecting '1' to get output to signify a successful result.

If you need to manually catch your exception so you can run some other assertions like we did above, you’ll need to do it differently:

try {
	$this->_handleAjax( 'my_ajax_action' );
} catch ( WPAjaxDieStopException $e ) {
	// We expected this, do nothing.
}

// Check that the exception was thrown.
$this->assertTrue( isset( $e ) );

// The output should be a 1 for success.
$this->assertEquals( '1', $e->getMessage() );

$this->assertEquals( 'yes', get_option( 'some_option' ) );

But if you are outputting your data directly instead of using wp_die(), you need to do it differently. One example might be if you are using wp_send_json_success() to send a JSON response. In this case, the output is caught by _handleAjax() and stored in $this->_last_response. So you could check for the correct JSON response like this:

try {
	$this->_handleAjax( 'my_ajax_action' );
} catch ( WPAjaxDieStopException $e ) {
	// We expected this, do nothing.
}

$response = json_decode( $this->_last_response );
$this->assertInternalType( 'object', $response );
$this->assertObjectHasAttribute( 'success', $response );
$this->assertTrue( $response->success );

Setting the User Role

Many times an Ajax callback isn’t intended for all users. You may be saving something that only users with administrator permissions should be allowed to save. The Ajax test case class provides a handy helper function to let you set the current user’s role. For example, if your Ajax callback should only work for administrators, you may want to test that just any subscriber can’t come along and use it. To do this, you would set the user’s role before calling _handleAjax(), like this:

$this->_setRole( 'subscriber' );

And if you want to make sure that the administrators will have the permissions necessary to use it, you would set the role to 'administrator' instead:

$this->_setRole( 'administrator' );

You can also run as a logged-out user:

$this->logout();

Running Your Tests

Based on the examples above, our final testcase might look something like this:

/**
 * Test case for the Ajax callback to update 'some_option'.
 *
 * @group ajax
 */
class My_Some_Option_Ajax_Test extends WP_Ajax_UnitTestCase {

	/**
	 * Test that the callback saves the value for administrators.
	 */
	public function test_some_option_is_saved() {

		$this->_setRole( 'administrator' );

		$_POST['_wpnonce'] = wp_create_nonce( 'my_nonce' );
		$_POST['option_value'] = 'yes';

		try {
			$this->_handleAjax( 'my_ajax_action' );
		} catch ( WPAjaxDieStopException $e ) {
			// We expected this, do nothing.
		}

		// Check that the exception was thrown.
		$this->assertTrue( isset( $e ) );

		// The output should be a 1 for success.
		$this->assertEquals( '1', $e->getMessage() );

		$this->assertEquals( 'yes', get_option( 'some_option' ) );
	}

	/**
	 * Test that it doesn't work for subscribers.
	 */
	public function test_requires_admin_permissions() {

		$this->_setRole( 'subscriber' );

		$_POST['_wpnonce'] = wp_create_nonce( 'my_nonce' );
		$_POST['option_value'] = 'yes';

		try {
			$this->_handleAjax( 'my_ajax_action' );
		} catch ( WPAjaxDieStopException $e ) {
			// We expected this, do nothing.
		}

		// Check that the exception was thrown.
		$this->assertTrue( isset( $e ) );

		// The output should be a -1 for failure.
		$this->assertEquals( '-1', $e->getMessage() );

		// The option should not have been saved.
		$this->assertFalse( get_option( 'some_option' ) );
	}
}

And our Ajax callback might look like this:

/**
 * Ajax callback to save the 'some_option' option.
 */
function my_some_option_ajax_callback() {

	check_ajax_referer( 'my_nonce' );

	if ( ! isset( $_POST['option_value'] ) || ! current_user_can( 'manage_options' ) ) {
		wp_die( '-1' );
	}

	update_option( 'some_option', $_POST['option_value'] );

	wp_die( '1' );
}
add_action( 'wp_ajax_my_ajax_action', 'my_some_option_ajax_callback' );

Notice that I added @group ajax to the testcase docblock? That isn’t necessary, but you will probably want to do it, because it lets you easily run just your Ajax tests. Also, you will probably want to exclude the Ajax group from running by default, the same way WordPress does. The reason is because the tests can be very slow. The Ajax tests are so slow because all of the default Ajax callbacks in WordPress core get hooked up before each test is run. There are quite a few, and this takes some time. I don’t think this feature is actually necessary, and maybe it will be removed in future, especially if the test suite starts preserving hook state between tests. It also calls 'admin_init' every time, which is also slowing things down.

So that’s it. There really isn’t much to the Ajax unit tests, but it saved me from breaking the code I was refactoring. And hey, after all, that’s what unit tests are for.