WP Test Utils

https://github.com/yoast/wp-test-utils
Admin
WP Test Utils provides utilities for running automated tests for WordPress plugins and themes,...
Tokens:2,135
Snippets:12
Trust Score:9.1
License:BSD-3-Clause
Update:1 year ago
Show doc for...
Tokens:
Raw
### PHP Integration Test Case Example

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

Demonstrates the basic implementation of a WordPress integration test class using WP Test Utils. It extends the provided `TestCase` and includes a `set_up` method for custom test setup, ensuring compatibility with WordPress core testing utilities.

```PHP
<?php
namespace PackageName\Tests;

use Yoast\WPTestUtils\WPIntegration\TestCase;

class FooTest extends TestCase {
    protected function set_up() {
        parent::set_up();
        // Your own additional setup.
    }
}
```

--------------------------------

### Install WP Test Utils with Composer

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

This command installs the WP Test Utils package as a development dependency using Composer. It ensures that the package and its required dependencies are downloaded and configured for your project.

```Bash
composer require --dev yoast/wp-test-utils
```

--------------------------------

### Manually Load Plugin for Integration Tests (PHP)

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

This example shows how to manually load a plugin within a WordPress integration test bootstrap file using the WPTestUtils. It defines a callback function to load the plugin and hooks it into the 'muplugins_loaded' filter, then bootstraps WordPress.

```php
use Yoast\WPTestUtils\WPIntegration;

require_once dirname( __DIR__ ) . '/vendor/yoast/wp-test-utils/src/WPIntegration/bootstrap-functions.php';

$_tests_dir = WPIntegration\get_path_to_wp_test_dir();

// Get access to tests_add_filter() function.
require_once $_tests_dir . 'includes/functions.php';

/**
 * Callback to manually load the plugin
 */
function _manually_load_plugin() {
    require_once __DIR__ . '/relative/path/to/main-file.php';
}

// Add plugin to active mu-plugins to make sure it gets loaded.
tests_add_filter( 'muplugins_loaded', '_manually_load_plugin' );

/*
 * Bootstrap WordPress. This will also load the Composer autoload file, the PHPUnit Polyfills
 * and the custom autoloader for the TestCase and the mock object classes.
 */
WPIntegration\bootstrap_it();
```

--------------------------------

### PHPUnit TestCase with BrainMonkey Stubbing

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

This snippet demonstrates how to extend the BrainMonkey `TestCase` from Yoast WP Test Utils. It shows the setup and teardown methods and how to use `stubTranslationFunctions()` and `stubEscapeFunctions()` for testing string translation and output escaping, with options for applying or bypassing HTML escaping.

```PHP
<?php
namespace PackageName\Tests;

use Yoast\WPTestUtils\BrainMonkey\TestCase;

class FooTest extends TestCase {
    protected function set_up() {
        parent::set_up();
        // Your own additional setup.
    }

    protected function tear_down() {
        // Your own additional tear down.
        parent::tear_down();
    }

    public function testAFunctionContainingStringTranslating() {
        $this->stubTranslationFunctions(); // No HTML escaping will be applied.
        // Or:
        \Brain\Monkey\Functions\stubTranslationFunctions(); // HTML escaping will be applied.

        // Test your code.
    }

    public function testAFunctionContainingOutputEscaping() {
        $this->stubEscapeFunctions(); // No HTML escaping will be applied.
        // Or:
        \Brain\Monkey\Functions\stubEscapeFunctions(); // HTML escaping will be applied.

        // Test your code.
    }
}

```

--------------------------------

### PHP: Create Test Doubles for Unavailable Classes (Test Class)

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

This snippet shows how to create test doubles for unavailable classes within a PHP test class using `Yoast\WPTestUtils\BrainMonkey\TestCase::makeDoublesForUnavailableClasses` or `Yoast\WPTestUtils\BrainMonkey\TestCase::makeDoubleForUnavailableClass`. It includes an example of setting properties on a mocked 'WP_Post' object.

```PHP
<?php
namespace PackageName\Tests;

use Mockery;
use WP_Post;
use wpdb;
use Yoast\WPTestUtils\BrainMonkey\TestCase;

class FooTest extends TestCase {
    protected function set_up_before_class() {
        parent::set_up_before_class();
        self::makeDoublesForUnavailableClasses( [ WP_Post::class, wpdb::class ] );
        // or if only one class is needed:
        self::makeDoubleForUnavailableClass( WP_Post::class );
    }

    public function testSomethingWhichUsesWpPost() {
        $wp_post = Mockery::mock( WP_Post::class );
        $wp_post->post_title = 'my test title';
        $wp_post->post_type  = 'my_custom_type';

        $this->assertSame( 'expected', \function_under_test( $wp_post ) );
    }
}

```

--------------------------------

### Bootstrap WordPress Integration Tests (PHP)

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

This snippet demonstrates how to use the WPIntegration bootstrap utilities to set up WordPress integration tests. It includes defining the plugin directory, setting active plugins, and calling the bootstrap function to load WordPress and necessary test components.

```php
use Yoast\WPTestUtils\WPIntegration;

if ( getenv( 'WP_PLUGIN_DIR' ) !== false ) {
    define( 'WP_PLUGIN_DIR', getenv( 'WP_PLUGIN_DIR' ) );
}

$GLOBALS['wp_tests_options'] = [
    'active_plugins' => [ 'plugin-name/main-file.php' ],
];

require_once dirname( __DIR__ ) . '/vendor/yoast/wp-test-utils/src/WPIntegration/bootstrap-functions.php';

/*
 * Bootstrap WordPress. This will also load the Composer autoload file, the PHPUnit Polyfills
 * and the custom autoloader for the TestCase and the mock object classes.
 */
WPIntegration\bootstrap_it();

if ( ! defined( 'WP_PLUGIN_DIR' ) || file_exists( WP_PLUGIN_DIR . '/plugin-name/main-file.php' ) === false ) {
    echo PHP_EOL,
        'ERROR: Please check whether the WP_PLUGIN_DIR environment variable is set and set to the correct value. The integration test suite won't be able to run without it.',
        PHP_EOL;
    exit( 1 );
}
```

--------------------------------

### BrainMonkey Bootstrap File for WordPress Testing

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

A bootstrap file for PHPUnit that defines essential WordPress constants and clears the PHP Opcache. This is crucial for testing WordPress plugins and themes, ensuring a consistent environment.

```PHP
// File: tests/bootstrap.php
require_once dirname( __DIR__ ) . '/vendor/yoast/wp-test-utils/src/BrainMonkey/bootstrap.php';
require_once dirname( __DIR__ ) . '/vendor/autoload.php';
```

--------------------------------

### Yoast TestCase for BrainMonkey

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

Extends YoastTestCase to leverage BrainMonkey's stubbing capabilities for WordPress functions. This provides a testing environment with pre-defined return values for common WordPress functions.

```PHP
namespace PackageName\Tests;

use Yoast\WPTestUtils\BrainMonkey\YoastTestCase;

class FooTest extends YoastTestCase {
    // Your test code.
}
```

--------------------------------

### Update WP Test Utils with Composer

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

This command updates the WP Test Utils package to the latest version and also updates its dependencies. The `--with-dependencies` flag ensures that any changes in the package's dependencies are also handled.

```Bash
composer update --dev yoast/wp-test-utils --with-dependencies
```

--------------------------------

### PHP: Create Test Doubles for Unavailable Classes (Bootstrap)

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

This snippet demonstrates how to use `Yoast\WPTestUtils\BrainMonkey\makeDoublesForUnavailableClasses` in a test bootstrap file to create fake test double classes for unavailable classes like 'WP_Post' and 'wpdb'. This is useful for setting up test doubles for an entire test suite.

```PHP
<?php
// File: tests/bootstrap.php
require_once dirname( __DIR__ ) . '/vendor/yoast/wp-test-utils/src/BrainMonkey/bootstrap.php';
require_once dirname( __DIR__ ) . '/vendor/autoload.php';

Yoast\WPTestUtils\BrainMonkey\makeDoublesForUnavailableClasses( [ 'WP_Post', 'wpdb' ] );

```

--------------------------------

### PHP: Normalize Line Endings

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

A helper function intended for use with PHPUnit's setOutputCallback() to normalize line endings in the actual output before comparison with expected output.

```PHP
normalizeLineEndings( $output )
```

--------------------------------

### PHP: Expect Output Contains Substring

Source: https://github.com/yoast/wp-test-utils/blob/develop/README.md

Verifies if the generated output contains a specific substring, with an option to ignore differences in line endings. This method can only be used once per test; for multiple checks, use a data provider.

```PHP
expectOutputContains( $expected, $ignoreEolDiff = true )
```
Tokens:
Raw