lipemat/wp-unit

Forked Wp-unit with support for testing against existing database and other environment enhancements.

3.7.2 2024-04-23 14:57 UTC

Requires

• php: >=7.2.0
• dg/bypass-finals: ^1.5
• yoast/phpunit-polyfills: ^2.0.0

MIT

• lipemat

README

Fork of wp-unit to support bootstrapping an existing database and many other enhancements.

Original may be cloned from here: git://develop.git.wordpress.org/tests/phpunit

Usage

Install using composer either in you project or in a global location to be used among all projects.

composer require --dev lipemat/wp-unit

Example phpunit.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Version 1.2.0 -->
<phpunit backupGlobals="false"
         backupStaticAttributes="false"
         colors="true"
         convertDeprecationsToExceptions="true"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true"
         processIsolation="false"
         stopOnFailure="true"
         bootstrap="bootstrap.php"
>
    <php>
        <env name="HTTP_HOST" value="starting-point.loc" />
    </php>
    <testsuites>
        <testsuite name="Starting Point">
            <directory>./tests</directory>
        </testsuite>
    </testsuites>
</phpunit>

Example bootstrap.php file

<?php
require __DIR__ . '/wp-tests-config.php'
require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/vendor/lipemat/wp-unit/includes/bootstrap.php';

Example wp-tests-config.php

<?php
define( 'DB_NAME', 'tests' );
define( 'DB_USER', 'user' );
define( 'DB_PASSWORD', 'password' );
define( 'DB_HOST', 'localhost' );

define( 'ABSPATH', WP_TESTS_DIR . '/' );
define( 'DOMAIN_CURRENT_SITE', 'wp-libs.loc' );
define( 'WP_TESTS_CONFIG_FILE_PATH',  __FILE__ );
define( 'WP_PHP_BINARY', 'php' );
// Root of your site/
define( 'WP_TESTS_DIR', dirname( __DIR__ ) );
define( 'WP_TESTS_DOMAIN', 'tests.loc' );
define( 'WP_TESTS_DOMAIN', 'wp-libs.loc' );
define( 'WP_TESTS_EMAIL', '[e-mail]' );
define( 'WP_TESTS_TITLE', 'WordPress Unit Tests' );
define( 'WP_UNIT_DIR', __DIR__ . '/vendor/lipemat/wp-unit' );

// If using snapshot testing.
define( 'WP_TESTS_SNAPSHOTS_BASE', 'Lipe\Project' );
define( 'WP_TESTS_SNAPSHOTS_DIR', __DIR__ . '/__snapshots__' );

// If your not bootstrapping an exiting database.
define( 'WP_TESTS_TABLE_PREFIX', 'tests_' );

// If your tests must use `https` URL.
define( 'WP_TESTS_SSL', true );

Example unit test /tests/ExampleTest.php

<?php
class ExampleTest extends WP_UnitTestCase {
	public function test_examples() : void {
		$this->assertTrue( true );
		$this->assertFalse( false );
	}
}

Run the test suite like any other phpunit suite

phpunit

Excluding PHPUnit From Composer

If you are using an external PHP Unit executable or .phar and do not want phpunit/phpunit to be installed as part of your composer vendor, you may add the following configuration to your composer.json file.

{
  "replace": {
    "phpunit/phpunit": "*"
  }
}

Enhancements

Network Options

Setting a wp_tests_options value may also be used to set a network option. Set test options like normal, and they will automatically replace network option values as well.

<?php
$GLOBALS['wp_tests_options'][ 'site_name' ] = 'Example Site Name';

Run all scheduled crons

Used for testing crons by running them if they are schedule to run.

wp_cron_run_all()

Local wp-tests-config.php

You may set up your wp-tests.config.php in the directory of your bootstrap.php and phpunit.xml. Really this can be put anywhere as long as you point to it in your bootstrap.php file.

<?php
require __DIR__ . '/wp-tests-config.php';

Bootstrap WP on existing database

Using the bootstrap-no-install.php allows you to test against your current data in the database. Out of the box it supports MySQL transactions to allow tests to set and use data without actually storing it in the database.

1. Update your wp-tests-config.php file to point to database you want to use.
2. Change your bootstrap.php to use the bootstrap-no-install.php file like so;

<?php
require __DIR__ . '/wp-tests-config.php';
require __DIR__ . '/vendor/lipemat/wp-unit/includes/bootstrap-no-install.php';

Gotchas:

1. If you override the WP_UnitTestCase::setUp() method in your test class, be sure to call parent::setUp(). Otherwise, any data you set during tests will persist to the database.
2. If your database tables are using MyISAM storage engines, data will persist. They may be converted to InnoDB or any other engine which supports transactions.

Global filters which apply to all tests

From within your wp-tests-config.php file add some filters to the $GLOBALS[ 'wp_tests_filters' ]

<?php
$GLOBALS[ 'wp_tests_filters' ][ 'the_title' ] = function ( $title ) {
	return 'Example Title';
};

Turn on mail sending

<?php
define( 'WP_TESTS_SEND_MAIL', true );

Set a memory limit

From within your wp-tests.config.php add a custom memory limit.

<?php
define( 'WP_MEMORY_LIMIT', '128M' );

Allow an outside languages directory

From within your wp-tests.config.php add a custom language directory.

<?php
define( 'WP_LANG_DIR', __DIR__ . '/languages' );

Prevent plugins from breaking mysql transactions

Some third party plugins use their own transactions which cause unpredictable results with the transactions used by wp-unit.

This library automatically accounts for outside transactions.

Support custom ajax methods.

Sometimes you want to use ajax responses to calls which live outside the wp_ajax actions.

This library adds methods to WP_Ajax_UnitTestCase:

1. _handleAjaxCustom which will turn any callable into an wp_ajax action then call it via _handleAjax.
2. _getJsonResult call any callable which uses wp_send_json_success or wp_send_json_error and return the result.

Support raw request testing.

Sometimes you want to verify requests are actually going out and not just assert that a method which sends requests is being called.

1. Extend the WP_Http_Remote_Post_TestCase from your test's class.
2. All requests will not send but instead be stored in the test's class' properties.
3. Retrieve sent via $this->get_sent().
4. Mock raw responses via $this->mock_response.

Support object cache testing

For testing your object cache a helper TestCase is available. Automatically resets for a fresh object cache between tests.

1. Extend the Object_Cache_TestCase from your test's class.
2. Interact with $this->object_cache to access your object cache.
3. Use include helper assertions and utilities.
   1. assertNotCacheExternal - Assert a key is not available in the external cache.
   2. assertCacheExternal - Assert a key is available in the external cache.
   3. assertCachePropertyAndExternal - Assert a value is same in the runtime cache as external cache.
   4. get_cache_key - Get parsed key sent to external cache.

Automatically generate files for Attachment factory.

Many follow-up attachment calls require the attachment to have an actual file attached to it. For example get_the_post_thumbnail_url will always be empty if a file does not exist.

This automatically adds files to the create call via self::factory()->attachment.

<?php
$post = self::factory()->post->create_and_get();
$attachment = self::factory()->attachment->create_and_get();
set_post_thumbnail( $post->ID, $attachment->ID );
// Will return something like `https:///wp-content/uploads//tmp/canola.jpg`
get_the_post_thumbnail_url( $post->ID );

Support assertEqualSetsValues on all TestCases

Support testing two arrays of values while accounting for order but ignoring array keys. Useful for testing things like pagination.

Example:

$categories = \get_categories( [
			'orderby' => 'term_id',
			'order'   => 'ASC',
		] );
$per_page = 20;
$this->assertEqualSetsValues(
			wp_list_pluck( array_slice( $categories, $per_page * 4, $per_page ), 'term_id' ),
			wp_list_pluck( $this->get_results( 5 )->categories, 'id' )
		)

Support assertEqualSetsIndex on all TestCases

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

Support mocking final classes.

Includes a utilities library to enable mocking of any final classes.

db/bypass-finals

Enable for tests via.

DG\BypassFinals::enable();

Internal Merging Core Process

The original repo this is forked from contains the entire WordPress code base along with the tests directory and is not feasible for a typical git merge.

Instead, merging in changes from WordPress core is done via patches.

1. Checkout the latest master from git clone git://develop.git.wordpress.org/tests
2. cd tests/tests/phpunit
3. git diff <last commit merged in> trunk --relative > <lastest master commit>.<date>.patch
   1. Change <last commit merged in> to name of the latest patch in the /patches directory which matches the latest commit merged it.
   2. Change <lastest trunk commit> latest commit of master.
   3. Change <date> to today's date.
4. Move new patch file to /patches directory:
5. Apply the patch to this repository using either:
   1. Terminal:
      1. git apply --reject --whitespace=fix patches/<lastest trunk commit>.<date>.patch
      2. Delete the tests directory (not included in this repo).
      3. Use log or search for .rej and solve the rejections manually.
   2. Use PHPStorm's interactive built in "Apply Patch" (preferred):
      1. Git menu in the toolbar.
      2. Patch -> Apply Patch
      3. Uncheck the tests directory (not included in this repo).
6. Make sure to note the commit merged in the git log and release notes if applicable.