The Guide to WordPress Unit Testing Assertions

The WordPress Unit Testing Framework contains a set of custom assertion helper methods which help with writing unit test.

In this post, we’ll present these helper methods available through the WP_UnitTestCase case class. Each method is presented with its function signature, a description of what it does, as well as a sample usage in a unit test.

Table of Contents

• assertEqualSets
  • Description
  • Sample Usage
• assertEqualSetsWithIndex
  • Description
  • Sample Usage
• assertNonEmptyMultidimensionalArray
  • Description
• assertNotWPError
  • Description
  • Sample Usage
• assertQueryTrue
  • Description
  • Sample Usage
• assertWPError
  • Description
  • Sample Usage

assertEqualSets

Description

assertEqualSets( array $expected, array $actual )

Asserts that the contents of two un-keyed, single arrays are equal, without accounting for the order of elements.

Sample Usage

class AssertEqualSetsTest extends WP_UnitTestCase {
     public function test_wp_list_util_get_unmodified_output() {
         $input = [ 'foo', 'bar' ];
         $util  = new WP_List_Util( $input );

         $this->assertEqualSets( $input, $util->get_output() );
     }
}

assertEqualSetsWithIndex

Description

assertEqualSetsWithIndex( array $expected, array $actual )

Asserts that the contents of two keyed, single arrays are equal, without accounting for the order of elements.

Sample Usage

class AssertEqualSetsWithIndexTest extends WP_UnitTestCase {
     public function test_register_post_type_adds_post_type_features() {
         // Register a post type with a couple of post type supports.
         register_post_type(
             'foo',
             [
                 'supports' => [
                     'editor',
                     'title',
                     'author',
                 ],
             ]
         );

         // Verify that the global holding the registered post type supports has been updated.
         $this->assertEqualSetsWithIndex(
             [
                 'author' => true,
                 'editor' => true,
                 'title'  => true,
             ],
             $GLOBALS['_wp_post_type_features']['foo']
         );
    }
}

assertNonEmptyMultidimensionalArray

Description

assertNonEmptyMultidimensionalArray( array $array )

Asserts that the given variable is a multidimensional array, and that all arrays are non-empty. This makes this method only useful for checking the format of a data structure.

assertNotWPError

Description

Asserts that the contents of $actual is not an instance of WP_Error.

assertNotWPError( mixed $actual, string $message = '' )

This method is a wrapper around PHPUnit’s assertNotInstanceOf().

When the assertion fails, the error message contained in the WP_Error will be output by the test runner. This helps with finding the cause of failing tests.

While assertNotWPError verifies that a function did not fail, there should be additional assertions, to verify the success criteria.

Sample Usage

class AssertNotWPErrorTest extends WP_UnitTestCase {
     public function test_set_post_format() {
          $result = set_post_format( self::factory()->post->create(), 'aside' );

          // Verify that the post format was set.
          $this->assertNotWPError( $result );

          // Verify that the right post format was set.
          $aside_term = get_term_by( 'slug', 'post-format-aside', 'post_format' );
          $this->assertSame( [ $aside_term->term_id ], $result );
     }
}

assertQueryTrue

Description

assertQueryTrue( string $properties )

WordPress offers procedural wrapper functions, called query tags, to access properties of the main WP_Query instance. An example is is_single(), which returns the value of $GLOBALS['wp_query']->is_single.

The assertQueryTrue() method helps you verify that properties of the main query are true. It accepts the names of the query tags that should return true.

Sample Usage

class AssertQueryTrueTest extends WP_UnitTestCase {
    public function test_tag_archive_query_tags() {
        // Setup the query variables for a post tag archive.
        $this->go_to( get_term_link( self::factory()->tag->create() ) );

        // Verify that `is_tag()` and `is_archive()` return `true`.
        $this->assertQueryTrue( 'is_tag', 'is_archive' );
    }
}

assertWPError

Description

assertWPError( mixed $actual, string $message = '' )

Asserts that the contents of $actual is an instance of WP_Error.

This method is a wrapper around PHPUnit’s assertInstanceOf(), and shares the same signature. When the assertion fails, the text in $message will be output by the test runner.

It is common for functions to return multiple errors, to make your tests useful, you need to add additional assertions for the error message that was returned.

Sample Usage

class AssertWPErrorTest extends WP_UnitTestCase {
    public function test_wp_insert_user_empty_user_login() {
        // Create a user with an empty login.
        $return = wp_insert_user( [
            'user_login' => '',
            'user_pass'  => 'password',
        ] );

        // Verify that a WP_Error is returned, and that the right error code is set.
        $this->assertWPError( $return );
        $this->assertSame( $return->get_error_code(), 'empty_user_login' );
    }
}