Brain Monkey

https://giuseppe-mazzapica.gitbook.io/brain-monkey
Admin
Brain Monkey is a PHP unit test utility that allows mocking and testing of any PHP function, with...
Tokens:11,617
Snippets:144
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Query documentation via HTTP GET

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/llms.txt

Perform a GET request to the documentation index using the ask and goal parameters to receive a direct answer and relevant excerpts.

```http
GET https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-expect.md?ask=<question>&goal=<end_goal>
```

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

### Example Class with Hooks

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

The target class containing add_action and add_filter calls to be tested.

```php
namespace Some\Name\Space;

class MyClass {

    public function addHooks() {

       add_action('init', [__CLASS__, 'init'], 20);
       add_filter('the_title', [__CLASS__, 'the_title'], 99);
    }
}
```

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

### Class with Dynamic Method Hook

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

A class example using an instance method as a hook callback.

```php
namespace Some\Name\Space; 

class MyClass {

    public function init() {
      /* ... */
    }

    public function addHooks() {
       add_action('init', [ $this, 'init' ], 20);
    }
}
```

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

### Closure with Type-hints and Variadic Arguments

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Example of a closure with complex type-hints and its corresponding identification string.

```php
namespace Foo\Bar;

function( array $foo, Baz $baz, Bar ...$bar) {
  // ....
}
```

```php
'function ( array $foo, Foo\Bar\Baz $baz, Foo\Bar\Bar ...$bar )';
```

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

### Static Closure Identification

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Example of a static closure and its corresponding identification string.

```php
static function( int $foo, Bar ...$bar ) {
  // ....
}
```

```php
'static function ( int $foo, Bar ...$bar )';
```

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

### Example Class with Closure Hook

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

A sample class defining a closure within an add_filter call.

```php
namespace Some\Name\Space; 

class MyClass {

  public function addHooks() {

       add_filter('the_title', function($title) {
          return $title;
       }, 99);
    }
}
```

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

### Define a class with a nested action

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Example class containing a method that triggers an action.

```php
class MyClass {

    function doStuff() {
        do_action( 'trigger_an_hook' );
    }
}
```

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

### Install Brain Monkey via Composer CLI

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/general/installation.md

Use this command in your project root to add Brain Monkey as a development dependency.

```bash
composer require brain/monkey:2.* --dev
```

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

### Define a class with an action hook

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Example class containing a method that triggers a WordPress action.

```php
class MyClass {

    public $post;

    function setPost() {

        global $post;
        $this->post = $post;

        do_action('my_class_set_post', $this);

        return $post;
    }
}
```

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

### Define a class with filter hooks

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Example class containing a method that applies multiple WordPress filters.

```php
class MyClass {

    function getValues() {

        $title   = apply_filters('my_class_title', '');
        $content = apply_filters('my_class_content', '');

        return [$title, $content];
    }
}
```

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

### Configure PHPUnit Base Test Case

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-setup.md

Create a custom test case class that calls Brain Monkey's setup and teardown methods to ensure proper initialization for every test.

```php
use PHPUnit\Framework\TestCase;
use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
use Brain\Monkey;

class MyTestCase extends TestCase {

    // Adds Mockery expectations to the PHPUnit assertions count.
    use MockeryPHPUnitIntegration;

    protected function setUp() {
        parent::setUp();
        Monkey\setUp();
    }

    protected function tearDown() {
        Monkey\tearDown();
        parent::tearDown();
    }
}
```

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

### GET /documentation-index

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/llms.txt

Performs a query against the documentation index to retrieve answers and relevant excerpts based on a natural language question.

```APIDOC
## GET /documentation-index

### Description
Perform an HTTP GET request on the documentation index to ask a specific question and optionally provide a broader goal for context.

### Method
GET

### Endpoint
https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-expect.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate question to be answered.
- **goal** (string) - Optional - The broader end goal to help tailor the response.

### Response
- The response contains a direct answer to the question along with relevant excerpts and sources from the documentation.
```

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

### Closure string representation details

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Examples of how different closure definitions are represented as strings in Brain Monkey v2.

```php
namespace A\Name\Space;

$closure_1 = static function( array $foo, SomeClass $bar, int ...$ids ) : bool { /* */ }

$closure_2 = function( array $foo, SomeClass $bar, array $ids = [] ) : bool { /* */ }

// $closure_1 is represented as:
"static function ( array $foo, A\Name\Space\SomeClass $bar, int ...$ids )";

// $closure_2 is represented as:
"function ( array $foo, A\Name\Space\SomeClass $bar, array $ids )";
```

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

### Callable validation in Brain Monkey v1

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Examples of callable arguments that would trigger failures in v1 if the referenced class or function was unavailable.

```php
// this fail in Brain Monkey v1 if `SomeClass` was not available 
// or if SomeClass::aMethod would not be a valid method
add_action( 'foo', [ SomeClass::class, 'aMethod' ] );

// this fail in Brain Monkey v1 if `Some\Name\Space\aFunction` is not available
add_action( 'bar', 'Some\Name\Space\aFunction' );
```

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

### Handling return expectations in v2

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Illustrates the requirement to define return expectations for all argument sets when a return expectation is added.

```php
Brain\Monkey\Filters\expectApplied('a_filter')->once()->with('Foo')->andReturn('Foo!');
Brain\Monkey\Filters\expectApplied('a_filter')->once()->with('Bar');

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

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

### Using andReturnFirstArg in v2

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Shows how to use andReturnFirstArg to handle catch-all filter behavior without explicit expectations for every argument.

```php
Brain\Monkey\Filters\expectApplied('a_filter')->once()->with('Foo')->andReturn('Foo!');
Brain\Monkey\Filters\expectApplied('a_filter')->zeroOrMoreTimes()->withAnyArgs()->andReturnFirstArg();

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

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

### Mocking namespaced functions

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-setup.md

Demonstrates how to mock both global and namespaced functions using fully qualified names.

```php
Functions\expect('a_global_function');

Functions\expect('My\\App\\awesome_function');
```

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

### Accessing Mockery API in Brain Monkey v1

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Demonstrates the two legacy methods for accessing the Mockery API using static class methods.

```php
// Brain Monkey v1 method one
Brain\Monkey::functions::expect('some_function');
Brain\Monkey::actions()->expectAdded('init');
Brain\Monkey::filters()->expectApplied('the_title');

// Brain Monkey v1 method two
Brain\Monkey\Functions::expect('some_function');
Brain\Monkey\WP\Actions::expectAdded('init');
Brain\Monkey\WP\Filters::expectApplied('the_title');
```

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

### Using andReturnFirstArg() in Brain Monkey v2

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Compares the new andReturnFirstArg() method in v2 with the manual callback approach required in v1.

```php
// Brain\Monkey v2:
Brain\Monkey\Functions\expect('foo')->andReturnFirstArg();
Brain\Monkey\Filters\expectApplied('the_title')->andReturnFirstArg();


// Brain\Monkey v1:
Brain\Monkey\Functions\expect('foo')->andReturnUsing(function($arg) {
  return $arg;
});

Brain\Monkey\Filters\expectApplied('the_title')->andReturnUsing(function($arg) {
  return $arg;
});
```

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

### Testing hooks with closures in Brain Monkey v2

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Illustrates the updated closure string representation in v2, which now includes parameter signatures.

```php
// Brain Monkey v2:
test();
self::assertNotFalse(has_action('example_one', 'A\Name\Space\SomeClass->aMethod()')); // pass
self::assertNotFalse(has_action('example_two', 'function()')); // fail!
self::assertNotFalse(has_action('example_two', 'function(array $foo)')); // pass!
```

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

### Testing hooks with closures in Brain Monkey v1

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Shows how hooks were tested in v1 using string representations for object methods and closures.

```php
namespace A\Name\Space;

function test() {

  add_action('example_one', [new SomeClass(), 'aMethod']);

  add_action('example_two', function(array $foo) { /* ... */ });
}
```

```php
// Brain Monkey v1:
test();
self::assertNotFalse(has_action('example_one', 'A\Name\Space\SomeClass->aMethod()')); // pass
self::assertNotFalse(has_action('example_two', 'function()')); // pass
```

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

### Mockery fluent interface chain

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Demonstrates the use of getMock() in Mockery to chain multiple method expectations.

```php
Mockery\mock(SomeClass::class)
  ->shouldReceive('exclamation')->with('Foo')->once()->andReturn('Foo!')
  ->getMock()
  ->shouldReceive('question')->with('Bar')->once()->andReturn('Bar?')
  ->getMock()
  ->shouldReceive('invert')->with('Baz')->once()->andReturn('zaB')
```

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

### v2 expectation behavior

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Demonstrates that expectations in v2 do not break default behavior if no return value is specified.

```php
Brain\Monkey\Filters\expectApplied('a_filter')->once()->with('Foo', 'Bar');

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

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

### Default apply_filters behavior

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Demonstrates the standard behavior where apply_filters returns the first argument provided.

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

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

### Functions\expect()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-expect.md

The entry-point for function testing in Brain Monkey. It accepts a function name and returns a Mockery expectation object to define behavior and constraints.

```APIDOC
## Functions\expect(string $functionName)

### Description
Sets expectations on a function's behavior, including how many times it is called, what arguments it receives, and what it returns.

### Signature
`Functions\expect(string $functionName): Mockery\Expectation`

### Parameters
- **$functionName** (string) - Required - The name of the function to set expectations on.

### Usage Examples

#### Call Count Expectations
```php
Functions\expect('paganini')->once();
Functions\expect('tween')->twice();
Functions\expect('who_knows')->zeroOrMoreTimes();
Functions\expect('i_should_run')->atLeast()->once();
Functions\expect('i_have_a_max')->atMost()->twice();
Functions\expect('poor_me')->never();
Functions\expect('pretty_precise')->times(3);
Functions\expect('i_have_max_and_min')->between(2, 4);
```

#### Argument Validation
```php
// Validate specific arguments
Functions\expect('function_name')->with('arg_1', 'arg2');

// Validate types
Functions\expect('function_name')->with(Mockery::type('resource'), Mockery::type('int'));

// Regex validation
Functions\expect('function_name')->with('/^foo/');
```

#### Forcing Behavior
```php
// Return a specific value
Functions\expect('function_name')->andReturn('Baz!');

// Use a callback
Functions\expect('function_name')->andReturnUsing(function() { return 'value'; });

// Throw an exception
Functions\expect('function_name')->andThrow('RuntimeException');
```
```

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

### Returning arguments with returnArg()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md

Configures a function to return a specific argument by index. Throws an exception if the argument index is not provided to the function.

```php
Functions\when('give_me_the_first')->returnArg(); // is the same of ->returnArg(1)
Functions\when('i_want_the_second')->returnArg(2);
Functions\when('and_the_third_for_me')->returnArg(3);

echo give_me_the_first('A', 'B', 'C'); // echoes "A"
echo i_want_the_second('A', 'B', 'C'); // echoes "B"
echo and_the_third_for_me('A', 'B', 'C'); // echoes "C"
```

```php
Functions\when('needs_the_third')->returnArg(3);

// throws an exception because required 3rd argument, but received 2
echo needs_the_third('A', 'B');
```

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

### Returning values with justReturn()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md

Configures a function to return a specific value or null if no argument is provided.

```php
Functions\when('a_undefined_function')->justReturn('Cool!');

echo a_undefined_function(); // echoes "Cool!"
```

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

### Verify Action Execution Count

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-tools.md

Demonstrates how Brain Monkey tracks the execution count of WordPress actions automatically.

```php
do_action('my_custom_action');

// something in the middle
$did = did_action('my_custom_action');
```

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

### Expectation behavior in Brain Monkey v1

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Demonstrates a test case in v1 where an expectation on an action does not cause a failure if the action is never called.

```php
class MyClass {

    public function doSomething() {
      return true;
    }
}


class MyClassTest extends MyTestCase {

    // this test passes in Brain Monkey v1
    public function testSomething() {
        \Brain\Monkey\WP\Actions::expectAdded('init'); // this has pretty much no effect
        $class = new MyClass();
        self::assertTrue($class->doSomething());
    }
}
```

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

### Test an action with whenHappen

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Demonstrates using 'whenHappen' to modify an object state when an action is triggered during a test.

```php
use Brain\Monkey\Actions;

class MyClassTest extends MyTestCase {

    function testFireHooksReturnValue() {

        Action\expectDone('my_class_set_post')
            ->with(Mockery::type(MyClass::class))
            ->whenHappen(function($my_class) {
                $my_class->post = (object) ['post_title' => 'Mocked!'];
            });

        ( new MyClass() )->setPost();

        $this->assertSame( 'Mocked!', $class->post->post_title );
    }
}
```

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

### Use withAnyargs for catch-all expectations

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Use withAnyargs in combination with andReturnFirstArg to create a catch-all expectation for filters.

```php
Filters\expectApplied('my_filter')->once()->with('bar')->andReturn('This time bar!');
// Catch all the other cases with the default:
Filters\expectApplied('my_filter')->once()->withAnyargs()->andReturnFirstArg();

// All the following passes!
self::assertSame( 'Foo', apply_filters( 'my_filter', 'Foo' ) );
self::assertSame( 'This time bar!', apply_filters( 'my_filter', 'Bar' ) );
self::assertSame( 'Meh!', apply_filters( 'my_filter', 'Meh!' ) );
```

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

### Testing Hooks with WordPress Functions

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Verifying hook registration using standard WordPress functions within a PHPUnit test case.

```php
use Some\Name\Space\MyClass;

class MyClassTest extends MyTestCase {

  public function testAddHooksActuallyAddsHooks() {

        ( new MyClass() )->addHooks();
        self::assertNotFalse( has_action('init', [ MyClass::class, 'init' ]) );
        self::assertNotFalse( has_filter('the_title', [ MyClass::class, 'the_title' ] ) );
    }
}
```

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

### Testing Dynamic Method Hooks

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Verifying hooks attached to dynamic methods using Brain Monkey's specialized string syntax.

```php
class MyClassTest extends MyTestCase
{
    public function testAddHooksActuallyAddsHooks()
    {
        $class = new \Some\Name\Space\MyClass\MyClass();
        $class->addHooks();

        self::assertSame( 20, has_action( 'init', 'Some\Name\Space\MyClass->init()' ) );
    }
}
```

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

### v1 expectation behavior

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Shows how adding an expectation in v1 would break the default return behavior.

```php
Brain\Monkey\WP\Filters::expectApplied('a_filter');

self::assertSame('Foo', apply_filters('a_filter', 'Foo', 'Bar')); // fails in v1
```

```php
Brain\Monkey\WP\Filters::expectApplied('a_filter')->andReturn('Foo');

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

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

### Test hook execution with did_action and Filters\applied

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Verifies that hooks were fired by checking their execution counts using Brain Monkey's filter utility and native WordPress functions.

```php
use Brain\Monkey\Filters;

class MyClassTest extends MyTestCase
{
    function testFireHooksActuallyFiresHooks()
    {
        ( new MyClass() )->fireHooks();

        $this->assertSame( 1, did_action('my_action') );
        $this->assertTrue( Filters\applied('my_filter') > 0 );
    }
}
```

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

### Define multiple function stubs with return values

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Pass an associative array where keys are function names and values are the desired return values.

```php
Functions\stubs(
    [
        'is_user_logged_in' => true,
        'current_user_can'  => false,
    ]
);
```

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

### Set expectations based on specific arguments

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Define different return values for a filter based on the specific arguments it receives.

```php
Filters\expectApplied('my_filter')->once()->with('foo')->andReturnFirstArg();
Filters\expectApplied('my_filter')->once()->with('bar')->andReturn('This time bar!');

self::assertSame( 'Foo', apply_filters( 'my_filter', 'Foo' ) );
self::assertSame( 'This time bar!', apply_filters( 'my_filter', 'Bar' ) );
```

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

### Accessing Mockery API in Brain Monkey v2

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Shows the consolidated functional approach for accessing the Mockery API in version 2.

```php
// Brain Monkey v2
Brain\Monkey\Functions\expect('some_function');
Brain\Monkey\Actions\expectAdded('init');
Brain\Monkey\Filters\expectApplied('the_title');
```

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

### Verify Filter Application

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-tools.md

Demonstrates how Brain Monkey handles WordPress filters by returning the original value when no filters are attached.

```php
$post = [ 'post_title' => 'My Title' ];

$title = apply_filters('the_title', $post['post_title']);
```

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

### Test WordPress Hooks with Expectations

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Use Actions\expectAdded and Filters\expectAdded to verify hook registration before executing the target code.

```php
use Brain\Monkey\Actions;
use Brain\Monkey\Filters;

class MyClassTest extends MyTestCase
{
    function testAddHooksActuallyAddsHooks()
    {
        Actions\expectAdded('init');

        Filters\expectAdded('the_title')->with(\Mockery::type('Closure'));

        // let's use the code that have to satisfy our expectations
       ( new \Some\Name\Space\MyClass() )->addHooks();
    }
}
```

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

### Functions\when()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md

The primary entry point for defining function behavior. It is used in conjunction with chaining methods to specify how a function should behave when called.

```APIDOC
## Brain\Monkey\Functions\when($functionName)

### Description
Defines the behavior for a function, allowing it to be mocked or defined if it does not exist.

### Parameters
- **$functionName** (string) - Required - The name of the function to patch.

### Chaining Methods
- **justReturn($value)**: Makes the function return the provided value.
- **returnArg($index)**: Makes the function return the argument at the specified 1-based index.
- **justEcho($value)**: Makes the function echo the provided value.
- **echoArg($index)**: Makes the function echo the argument at the specified 1-based index.
- **alias($callback)**: Makes the function behave like the provided callback.
```

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

### Demonstrate failing expectation due to missing argument match

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Expectations must be defined for all possible arguments a filter might receive, otherwise the test will fail.

```php
Filters\expectApplied('my_filter')->once()->with('foo')->andReturnFirstArg();
Filters\expectApplied('my_filter')->once()->with('bar')->andReturn('This time bar!');

self::assertSame( 'Foo', apply_filters( 'my_filter', 'Foo' ) );
self::assertSame( 'This time bar!', apply_filters( 'my_filter', 'Bar' ) );
self::assertSame( 'Meh!', apply_filters( 'my_filter', 'Meh!' ) );
```

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

### Use andReturnFirstArg helper

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

The andReturnFirstArg helper forces a filter to return its first argument, mimicking default WordPress behavior.

```php
Filters\expectApplied('my_filter')->once()->andReturnFirstArg();

self::assertSame( 'foo', apply_filters( 'my_filter', 'foo', 'bar' ) );
```

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

### Respond to filters with custom return values

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Use Mockery's andReturn or andReturnUsing methods to define custom return values for filtered hooks in tests.

```php
use Brain\Monkey\Filters;

class MyClassTest extends MyTestCase {

    function testFireHooksReturnValue() {

        Filters\expectApplied('my_filter')
            ->once()
            ->with('Filter applied', Mockery::type(MyClass::class))
            ->andReturn('Brain Monkey rocks!');

        $class = new MyClass();

        $this->assertSame('Brain Monkey rocks!', $class->fireHooks());
    }
}
```

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

### Test doing_action and nested hooks

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Verifies that 'doing_action()' correctly identifies the current and parent hooks during execution.

```php
use Brain\Monkey\Actions;

class MyClassTest extends MyTestCase {

    function testDoStuff() {

        // 'an_hook' action is done below in the "whenHappen" callback
        Actions\expectDone( 'an_hook' )->once()->whenHappen(function() {

           self::assertTrue( doing_action('an_hook') );

           // doing_action() also resolves the "parent" hook like it was WordPress!
           self::assertTrue( doing_action('trigger_an_hook') );
        });

        Actions\expectDone('trigger_an_hook')->once()->whenHappen(function() {
           if( current_filter() === 'trigger_an_hook' ) {
                 do_action('an_hook');
           }
        });
    }
}
```

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

### Functions\stubTranslationFunctions()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Creates stubs for a predefined list of common translation functions. The stubs return or echo the first received argument without performing actual translation.

```APIDOC
## Functions\stubTranslationFunctions()

### Description
Creates stubs for all standard translation functions (e.g., __(), _e(), _n(), translate()). The created stubs do not perform translation but return or echo the first received argument. For functions that translate and escape, the corresponding escaping mechanism is applied.

### Signature
`Functions\stubTranslationFunctions()`

### Supported Functions
- __()
- _e()
- _ex()
- _x()
- _n() (since 2.6)
- _nx() (since 2.6)
- translate()
- esc_html__()
- esc_html_x()
- esc_attr__()
- esc_attr_x()
- esc_html_e()
- esc_attr_e()
- _n_noop() (since 2.7)
- _nx_noop() (since 2.7)
- translate_nooped_plural() (since 2.7)
```

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

### Functions\stubs()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Defines multiple function stubs in bulk. It supports mapping function names to return values, aliasing functions to callables, or returning the first argument received.

```APIDOC
## Functions\stubs(array $stubs, mixed $default = null)

### Description
Defines multiple function stubs at once. Can be used with an associative array to map names to values, or a non-associative array with a default return value.

### Parameters
- **$stubs** (array) - Required - An array of function names. If associative, keys are function names and values are return values. If non-associative, values are function names.
- **$default** (mixed) - Optional - The return value for all functions in a non-associative array. Defaults to null (returns the first argument received).

### Usage Example
```php
\Functions\stubs([
    'is_user_logged_in' => true,
    '__' => null // Returns 1st argument
]);

\Functions\stubs(['is_admin', 'is_multisite'], true);
```
```

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

### Test fired hooks with expectations

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Use Actions\expectDone and Filters\expectApplied to verify that specific hooks are triggered with expected arguments during test execution.

```php
use Brain\Monkey\Actions;
use Brain\Monkey\Filters;

class MyClassTest extends MyTestCase
{
    function testFireHooksActuallyFiresHooks()
    {
        Actions\expectDone('my_action')
            ->once()
            ->with(Mockery::type(MyClass::class));

        Filters\expectApplied('my_filter')
            ->once()
            ->with('Filter applied', Mockery::type(MyClass::class));

        ( new MyClass() )->fireHooks();
    }
}
```

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

### Force function behavior and return values

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-expect.md

Use expectation methods to define return values, sequences, or exceptions for mocked functions.

```php
// return a specific value
Functions\expect('function_name')
  ->once()
  ->with('foo', 'bar')
  ->andReturn('Baz!');

// return values in order
Functions\expect('function_name')
  ->twice()
  ->andReturn('First time I run', 'Second time I run');

// return values in order, alternative
Functions\expect('function_name')
  ->twice()
  ->andReturnValues(['First time I run', 'Second time I run']);

// return noting
Functions::expect('function_name')
  ->twice()
  ->andReturnNull();

// use a callback for returning a value
Functions\expect('function_name')
  ->atLeast()
  ->once()
  ->andReturnUsing(function() {
      return 'I am an alias!';
  });

// makes function throws an Exception (e.g. to test try statements)
Functions\expect('function_name')
  ->once()
  ->andThrow('RuntimeException'); // Both exception names and object are supported
```

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

### Stub multiple functions to return their first argument

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Omitting the second argument defaults the return value to null, which triggers the 'return first argument' behavior for all provided function names.

```php
Functions\stubs(
    [
        'esc_attr',
        'esc_html',
        '__',
        '_x',
        'esc_attr__',
        'esc_html__',
    ]
);
```

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

### Stubbing functions that return callbacks

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Use a closure to return the desired callback, or use the when/justReturn API to avoid the default alias behavior of stubs.

```php
Functions\stubs(
   [
        'function_that_returns_a_callback' => function() { 
            return 'the_expected_returned_callback';
        }
   ]
);
```

```php
when('function_that_returns_a_callback')->justReturn('the_expected_returned_callback')
```

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

### Importing Functions namespace

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md

Required namespace import for using Brain Monkey function patching tools.

```php
use Brain\Monkey\Functions;
```

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

### Define a class with WordPress hooks

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

A sample class that triggers an action and applies a filter, used as the target for testing hook execution.

```php
class MyClass {

    function fireHooks() {

       do_action('my_action', $this);

       return apply_filters('my_filter', 'Filter applied', $this);
    }
}
```

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

### Stubbing functions that return null

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Use the __return_null WordPress function as the stub value to ensure the function returns null instead of the first argument.

```php
Functions\stubs( [ 'function_that_returns_null' => '__return_null' ] );
```

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

### Define function argument expectations

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-expect.md

Assert that functions are called with specific arguments, types, or patterns using Mockery argument matchers.

```php
// allow anything
Functions\expect('function_name')
  ->once()
  ->withAnyArgs();

// allow nothing
Functions\expect('function_name')
  ->once()
  ->withNoArgs();

// validate specific arguments
Functions\expect('function_name')
  ->once()
  ->with('arg_1', 'arg2');

// validate specific argument types
Functions\expect('function_name')
  ->times(3)
  ->with(Mockery::type('resource'), Mockery::type('int'));

// validate anything in specific places
Functions\expect('function_name')
    ->zeroOrMoreTimes()
    ->with(Mockery::any());

// validate a set of given arguments
Functions::expect('function_name')
    ->once()
    ->with(Mockery::anyOf('a', 'b', 'c'));

// regex validation
Functions\expect('function_name')
    ->once()
    ->with('/^foo/');

// excluding specific values
Functions\expect('function_name')
    ->once()
    ->with(Mockery::not(2, 3));

// dealing with array arguments
Functions\expect('function_name')
    ->once()
    ->with(Mockery::hasKey('foo'), Mockery::contains('bar', 'baz'));
```

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

### Mix different stubbing strategies

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Combine associative and non-associative arrays to define multiple stubbing behaviors in a single call.

```php
Functions\stubs(
    [
        // will both return 1st argument received, because `stubs` 2nd param defaults to `null`
        'esc_attr',
        'esc_html',

        // will all return what is given as array item value
        'is_user_logged_in'   => true,
        'current_user_can'    => false,
        'get_current_user_id' => 1,
    ]
);
```

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

### Closure Serialization Limitations

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Demonstrates how default values and return types are ignored during closure serialization.

```php
function( array $foo, $bar ) {
  // ....
}

function( array $foo = [], $bar = null ) {
  // ....
}

function( array $foo, $bar ) : array {
  // ....
}

function( array $foo, $bar = null ) : array {
  // ....
}
```

```php
'function ( array $foo, $bar )';
```

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

### Define stubs with callables and argument passthrough

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Use a callable as a value to alias the function, or null to return the first argument received by the stubbed function.

```php
Functions\stubs(
    [
        'is_user_logged_in'    => true,             // will return `true` as provided
        'wp_get_current_user' => function () {      // will return the WP_User mock
            return \Mockery::mock(\WP_User::class);
        },
        '__' => null,                               // will return the 1st argument received
    ]
);
```

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

### Echoing arguments with echoArg()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md

Configures a function to echo a specific argument by index.

```php
Functions\when('echo_the_first')->echoArg(); // is the same of ->echoArg(1)
Functions\when('echo_the_second')->echoArg(2);

echo_the_first('A', 'B', 'C'); // echoes "A"
echo_the_second('A', 'B', 'C'); // echoes "B"
```

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

### Add Brain Monkey to composer.json

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/general/installation.md

Manually add the dependency to your composer.json file if you prefer not to use the command line.

```json
{
  "require-dev": {
    "brain/monkey": "~2.0.0"
  }
}
```

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

### Echoing values with justEcho()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md

Configures a function to echo a specific value instead of returning it.

```php
Functions\when('a_undefined_function')->justEcho('Cool!');

a_undefined_function(); // echoes "Cool!"
```

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

### Stub multiple functions with the same return value

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

Pass a non-associative array of function names as the first argument and the shared return value as the second argument.

```php
Functions\stubs(
    [
        'is_user_logged_in',
        'current_user_can',
        'is_multisite',
        'is_admin',
    ],
    true
);
```

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

### Testing Closure Identification

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Using the serialized string representation to verify the closure was added.

```php
class MyClassTest extends MyTestCase
{
    public function testAddHooksActuallyAddsHooks()
    {
        $class = new \Some\Name\Space\MyClass();
        $class->addHooks();

        self::assertNotFalse( has_filter('the_title', 'function ($title)' ) );
    }
}
```

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

### Test current_filter resolution

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-done.md

Verifies that 'current_filter()' returns the expected hook name inside a filter callback.

```php
use Brain\Monkey\Filters;

class MyClassTest extends MyTestCase
{
    function testGetValues()
    {
        $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);

        $class = new MyClass();

        $this->assertSame(['Title', 'Content'], $class->getValues());
    }
}
```

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

### Aliasing functions with alias()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md

Configures a function to behave like another callback, such as a closure or a core function.

```php
Functions\when('duplicate')->alias(function($value) {
    return "Was ".$value.", now is ".($value * 2);
});

Functions\when('bigger')->alias('strtoupper');

echo duplicate(1); // echoes "Was 1, now is 2"
echo bigger('was lower'); // echoes "WAS LOWER"
```

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

### Functions\stubEscapeFunctions()

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/function-stubs.md

A helper function that automatically creates stubs for common WordPress escaping functions, providing basic escaping behavior for unit tests.

```APIDOC
## Functions\stubEscapeFunctions()

### Description
Creates stubs for WordPress escaping functions: esc_js, esc_sql, esc_attr, esc_html, esc_textarea, esc_url, esc_url_raw, and esc_xml. These stubs perform basic escaping on the first argument received.

### Usage Example
```php
\Functions\stubEscapeFunctions();
```
```

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

### Define function call frequency expectations

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-expect.md

Use these methods to assert how many times a specific function is called during a test.

```php
Functions\expect('paganini')->once();

Functions\expect('tween')->twice();

Functions\expect('who_knows')->zeroOrMoreTimes();

Functions\expect('i_should_run')->atLeast()->once();

Functions\expect('i_have_a_max')->atMost()->twice();

Functions\expect('poor_me')->never();

Functions\expect('pretty_precise')->times(3);

Functions\expect('i_have_max_and_min')->between(2, 4);
```

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

### Brain Monkey fluent expectation chaining

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/more/migrating-from-v1.md

Uses andAlsoExpectIt() to chain multiple expectations in Brain Monkey, replacing the unavailable getMock() method.

```php
Brain\Monkey\Filters\expectApplied('some_filter')
  ->once()->with('Hello')->andReturn('Hello!')
  ->andAlsoExpectIt()
  ->atLeast()->twice()->with('Hi')->andReturn('Hi!')
  ->andAlsoExpectIt()
  ->zeroOrMoreTimes()->withAnyArgs()->andReturnFirstArg();
```

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

### Preventing invalid return value expectations

Source: https://giuseppe-mazzapica.gitbook.io/brain-monkey/wordpress-specific-tools/wordpress-hooks-added.md

Attempting to force a return value on an added hook expectation will result in an exception.

```php
// this expectation will thrown an error!
Filters\expectAdded('the_title')->once()->andReturn(false);
```
Tokens:
Raw