README

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 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.
... allows testing in advanced complex projects.

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

Besides PHP and WordPress we do not require that much (see Packagist.org for more details):

phpUnit 6.5 - 9.5
mockery 1.3

Usage

If you start from scratch and do not have some bootstrapping already, then you can use our bootstrapping 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>

Using this bootstrap.php is not mandatory. Feel free to create a custom bootstrapping file, when you need to test CLI and admin stuff too.

Example

If you know PHPUnit already then asserting and mocking shouldn't be something new. With WPInt it can be for most PHPUnit Tests by adding one Trait:

class FooTest extends \PHPUnit\Framework\TestCase {

    use \Pretzlaw\WPInt\Traits\WordPressTests;
    
    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 )->andReturn( /* your wp post mock */ );
        $this->mockPostMeta( 'some_key' )->andReturn( 'Some value!' ); // For all posts
        $this->mockMetaData( 'my-own-cpt', 'another_key', 1337 )->andReturn( 'ec' ); // Just for ID 1337
        
        // Mock actions, filter, cache, ...
        $this->mockFilter( 'user_has_cap' )
             ->andReturn( true );
        
        $this->mockCache()
            ->shouldReceive('get')
            ->with('my_own_cache')
            ->andReturn('yeah');

        // Or use one of several shortcuts and helper
        $this->disableWpDie();
    }
}

As you see above we are using mockery/mockery:~1 which is easier to use and maintain but uses different method names (e.g. shouldReceive, andReturn as seen above).

List of all Assertions

assert Action Has Callback
assert Action Not Empty
assert Action Not Has Callback
assert Filter Empty
assert Filter Has Callback
assert Filter Not Empty
assert Filter Not Has Callback
assert Plugin Is Active
assert Plugin Is Not Active
assert Post Type Args
assert Post Type Labels
assert Post Type Registered
assert Shortcode Exists
assert Shortcode Has Callback
assert Shortcode Not Exists
assert Widget Exists
assert Widget Is Instance Of
assert Widget Is Not Instance Of
assert Widget Not Exists

List of WordPress Expectations / Mocks

expect Wp Post Insert Post
mock Cache
mock Current User
mock Filter
mock Get Post
mock Meta Data
mock Post Meta
mock Shortcode
mock User Meta

Other testing helper

backup Widgets
disable wp_die()
get All Shortcodes
get Shortcode Callback
get Widget Factory
get Wp Hooks
unregister All Widgets
unregister Widgets By Id

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

License

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.

pretzlaw / wp-integration-test

Maintainers

Details