Brain Monkey

In Brain Monkey v2, calling expectApplied() on a filter no longer breaks the default WordPress behavior where apply_filters() returns its first argument. You only need to define return values if you explicitly want to change that behavior.

Important: If you define a return expectation for a specific set of arguments, you must also define return expectations for all other possible argument sets that might be passed to that filter, otherwise the test will fail. To avoid manually defining every possible argument combination, use andReturnFirstArg() combined with Mockery's zeroOrMoreTimes()->withAnyArgs() to create a 'catch-all' expectation.

// Define a specific return for one case
Brain\Monkey\Filters\expectApplied('a_filter')->once()->with('Foo')->andReturn('Foo!');

// Use a catch-all to ensure other calls return the first argument instead of failing
Brain\Monkey\Filters\expectApplied('a_filter')->zeroOrMoreTimes()->withAnyArgs()->andReturnFirstArg();

self::assertSame('Foo!', apply_filters('a_filter', 'Foo')); // pass
self::assertSame('Bar', apply_filters('a_filter', 'Bar')); // pass

Brain Monkey correctly resolves WordPress hook state functions inside callbacks used for expectations. This allows you to write complex logic within andReturnUsing() or whenHappen() that relies on knowing which hook is currently active.

• current_filter(): Returns the name of the current hook being processed.
• doing_action(): Returns true if the current context is an action.
• doing_filter(): Returns true if the current context is a filter.

These functions also correctly resolve 'parent' hooks (e.g., if an action is triggered inside a callback for another action, doing_action() will return true for both).

// Using current_filter() inside a filter callback
$callback = function() {
    return current_filter() === 'my_class_title' ? 'Title' : 'Content';
};

Filters\expectApplied('my_class_title')->once()->andReturnUsing($callback);
Filters\expectApplied('my_class_content')->once()->andReturnUsing($callback);

Brain Monkey provides fine-grained control over WordPress plugin API functions, allowing you to test WordPress code in isolation without requiring a full WordPress bootstrap.

When Brain Monkey is loaded for tests, it automatically defines several core WordPress functions to prevent fatal errors and enable testing. This includes:

• Hook-related functions: add_action(), remove_action(), do_action(), did_action(), apply_filters(), add_filter(), etc.
• Generic functions: __return_true(), __return_false(), absint(), wp_json_encode(), is_wp_error(), etc.
• Translation and Escaping functions: Available via stubs.

With the WP hook API, Brain Monkey allows you to:

1. Test if an action or filter has been added (including frequency and arguments).
2. Test if an action or filter has been fired (including frequency and arguments).
3. Execute a callback when an action is fired to inspect passed arguments.
4. Execute a callback when a filter is applied to inspect arguments and return specific values.

Brain Monkey provides a "serialization" mechanism for closures, allowing you to identify them in has_action() or has_filter() using a string representation that mimics the PHP code used to define the closure.

Rules for Closure Strings:

• Namespace: Always use the fully qualified name for classes used in type-hints.
• Supported: Type-hints (including PHP 7+ scalar types), variadic arguments (...$args), and static closures.
• Ignored: Default argument values and PHP 7+ return type declarations are not included in the serialized string.

Example Serialization: If you define function( array $foo = [], $bar = null ) : array, it is serialized as 'function ( array $foo, $bar )'.

// Code to test
add_filter('the_title', function($title) {
    return $title;
}, 99);

// Test assertion
self::assertNotFalse( has_filter('the_title', 'function ($title)' ) );