# Testing: Hooks

## Introduction[​](#introduction "Direct link to Introduction")

Mantle provides an interface for testing WordPress hooks in declarative and assertive formats.

## Declaring Hook Usage[​](#declaring-hook-usage "Direct link to Declaring Hook Usage")

Inside your unit test you can declare the hook(s) you expect to fire and optionally specifying the amount of times and their return values. This is done via the `$this->expectApplied()` method.

Once declared, you can then run the subsequent function that will apply the WordPress filter and Mantle will handle the assertions.

```php
$this->expectApplied( 'action_to_check' )
	->twice()
	->with( 'value_to_check', 'secondary_value_to_check' );

```

### Defining Count[​](#defining-count "Direct link to Defining Count")

Define how many times a hook was applied. You can specify the number of times directly with `times()` or use `once()`, `twice()`, or `never()` instead.

```php
$this->expectApplied( 'action_to_check' )->once();
$this->expectApplied( 'action_to_check' )->twice();
$this->expectApplied( 'action_to_check' )->never();

// Perform the do_action() calls...

```

### Defining Arguments[​](#defining-arguments "Direct link to Defining Arguments")

Define the arguments that you expect to be passed to the filter. These would be the arguments passed to `do_action()`/`apply_filters()`/etc. at the start of the hook.

```php
$this->expectApplied( 'filter_to_check' )
	->once()
	->with( 'value_to_check' );

apply_filters( 'filter_to_check', 'value_to_check' );

```

### Defining Return Value[​](#defining-return-value "Direct link to Defining Return Value")

Define the expected return value for the filter. Return values can be specified using `andReturn(mixed $value)` or with some helper functions.

* `andReturn(mixed $value)`: Returns with the value of `$value`.
* `andReturnNull()`: Returns `null`.
* `andReturnTrue()`: Returns `true`.
* `andReturnTruthy()`: Returns `true` if the value is truthy.
* `andReturnFalse()`: Returns `false.`
* `andReturnFalsy()`: Returns `false` if the value is falsy.
* `andReturnEmpty()`: Returns `true` if the value is empty.
* `andReturnNotEmpty()`: Returns `false` if the value is not empty.
* `andReturnArray()`: Returns an array.
* `andReturnInstanceOf( string $class )`: Returns an instance of `$class`.
* `andReturnString()`: Returns a string.
* `andReturnInteger()`: Returns an integer.

```php
$this->expectApplied( 'falsey_filter_to_check' )
	->once()
	->andReturnFalse();

add_filter( 'falsey_filter_to_check', '__return_false' );
apply_filters( 'falsey_filter_to_check', true );

```

## Declaring Hook Added (add\_action/add\_filter)[​](#declaring-hook-added-add_actionadd_filter "Direct link to Declaring Hook Added (add_action/add_filter)")

You can use `expectAdded()` to declare that a hook was added to WordPress. This is useful for asserting that a hook was added with the correct arguments.

```php
// Check that "action_to_check" has any action added to it.
$this->expectAdded( 'action_to_check' );

// Check that "action_to_check" has a specific callable added to it.
$this->expectAdded( 'action_to_check', '__return_true' );

```

## Asserting Hook Usage[​](#asserting-hook-usage "Direct link to Asserting Hook Usage")

Hooks can be asserted against after they have already been applied. This can be done using the `$this->assertHookApplied()` method and can be used interchangeably with `expectApplied()`.

```php
// Assert that 'the_hook' was applied twice.
$this->assertHookApplied( 'the_hook', 2 );

// Assert that 'my_custom_hook' was not applied.
$this->assertHookNotApplied( 'my_custom_hook' );

```