WordPress Integration Test Helper

Mocking return value of functions/filters and more for testing WordPress with PHPUnit.

Writing tests with WordPress is a pain as the very old the official WordPress Unit Tests always require a lot of hands on for custom projects and other Testing-Frameworks try to mock the hell out of WordPress. The solution is to have a nice integration tests package that ...

• ... can be integrated into your already existing tests (using Traits).
• ... enabled you to test your package against other Plugins or Themes.
• ... ease testing down to the common PHPUnit style.

Overall the goal is simplicity and no time wasting crap (for me and you).

Install

Download or just

composer install --dev pretzlaw/wp-integration-test

We do not require that much (see Packagist.org for more details):

• PHP 7.0 - 7.4 or 8.0
• WordPress 4.6 - 5.6
• phpUnit 6.5 - 9.5
• mockery 1.3

Tests expand continuously to cover a bigger range one day (see Travis CI).

Usage

Either you have some of these or you need basic bootstrapping in the phpunit.xml or phpunit.dist.xml like this:

<phpunit bootstrap="vendor/Pretzlaw/WPInt/bootstrap.php">
	<testsuites>
		<testsuite name="default">
		    <!-- CHANGE THIS TO WHERE YOUR PHPUNIT TEST CLASSES ARE -->
			<directory>lib/tests</directory>
		</testsuite>
	</testsuites>
</phpunit>

The bootstrapping just loads WordPress as the wp-cli would do using the \Pretzlaw\WP_Int\run_wp() function.

Example

If you know PHPUnit already then mocking isn't something new (I hope). With WPInt it can be done like this:

class FooTest extends \PHPUnit\Framework\TestCase {

    use \Pretzlaw\WPInt\Traits\WordPressTests;
    // or via WPAssert::assert...() methods 
    
    function testBar() {
        // Assertions (simple or with special constraints)
        static::assertActionHasCallback( 'init', 'my_own_init' );
        static::assertShortcodeHasCallback(
            [ new IsInstanceOf( MyOwn::class ), 'some_method' ],
            'my_shortcode'
        );
        
        // Mock posts or meta-data
        $this->mockGetPost( 1337, [ 'post_content' => 'foobar' ] );
        $this->mockPostMeta( 'some_key', 'Some value!' ); // For all posts
        $this->mockMetaData( 'my-own-cpt', 'another_key', 'ec', 1337 ); // Just for ID 1337
        
        // Mock actions, mockFilter, mockCache, ...
        $this->mockFilter( 'user_has_cap' )
             ->andReturn( true );
        
        // Or make use of the shortcuts
        $this->mockCache()
            ->shouldReceive('get')
            ->with('my_own_cache')
            ->andReturn('yeah');

        $this->disableWpDie();
    }
}

Unfortunately the PHPUnit Mocking system changes often, which made it hard to establish compatibility with it. We are using mockery/mockery:~1 which is easier to use than PHPUnit Mocking and more stable but uses different method names (e.g. shouldReceive, andReturn as seen above).

Assertions

• ::assertActionHasCallback
• ::assertActionNotEmpty
• ->assertActionNotHasCallback
• ::assertFilterEmpty
• ::assertFilterHasCallback
• ::assertFilterNotEmpty
• ::assertFilterNotHasCallback
• ->assertPluginIsActive
• ->assertPluginIsNotActive
• ::assertPostTypeArgs
• ::assertPostTypeLabels
• ::assertPostTypeRegistered
• ::assertShortcodeExists
• ::assertShortcodeHasCallback
• ::assertShortcodeNotExists
• ::assertWidgetExists
• ::assertWidgetIsInstanceOf
• ::assertWidgetIsNotInstanceOf
• ::assertWidgetNotExists

Expectations / Mocks

• ->expectWpPostInsertPost
• ->mockCache
• ->mockCurrentUser
• ->mockFilter
• ::mockGetPost
• ->mockMetaData
• ->mockPostMeta
• ->mockShortcode
• ->mockUserMeta

Other helper

• ->backupWidgets
• ->disableWpDie
• ::getAllShortcodes
• ::getShortcodeCallback
• ::getWidgetFactory
• ::getWpHooks
• ->unregisterAllWidgets
• ->unregisterWidgetsById

Feel free to request for additional features or point out more common shortcuts by opening an issue.

License

Copyright 2021 Pretzlaw (rmp-up.de)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.