Oh Dear is the all-in-one monitoring tool for your entire website. We monitor uptime, SSL certificates, broken links, scheduled tasks and more. You'll get a notifications for us when something's wrong. All that paired with a developer friendly API and kick-ass documentation. O, and you'll also be able to create a public status page under a minute. Start monitoring using our free trial now.

How to test Laravel's invokable rules

Original – by Freek Van der Herten – 3 minute read

Laravel 9 introduced a new way to create custom validation rules: invokable rules. It allows you to write a custom validation rule with only one method: __invoke.

Here's a simple example:

namespace App\Rules;
 
use Closure;
use Illuminate\Contracts\Validation\InvokableRule;
 
class UppercaseRule implements InvokableRule
{
    public function __invoke(string $attribute, mixed $value, Closure $fail): void
    {
        if (strtoupper($value) !== $value) {
            $fail('The :attribute must be uppercase.');
        }
    }
}

If you want the rule to fail, your rule should execute the passed $fail closure and give it a good validation error message.

This way of writing custom validation rules will become the default in Laravel 10. (If you're writing your validation classes using the older syntax, no worries, that will still be supported in L10).

When I wrote my first invokable, I was figuring out how to test them. I came up with a nice solution (hat tip to Oliver Nybroe for pointing me in the right direction).

My preferred testing framework these days is Pest. In Pest, there is a way to write custom expectations. If you don't have experience with testing, Pest, or custom expectations, check out my course Testing Laravel, where you'll learn all this from scratch.

Here's the custom expectation I came up with:

expect()->extend('toPassWith', function(mixed $value) {
    $rule = $this->value;

    if (! $rule instanceof InvokableRule) {
        throw new Exception('Value is not an invokable rule');
    }

    $passed = true;

    $fail = function() use (&$passed) {
        $passed = false;
    };

    $rule('attribute', $value, $fail);

    expect($passed)->toBeTrue();
});

In this custom expectation, we'll invoke our rule and pass our own $fail closure to it. Using that $passed variable, we're going to detect if $fail was executed. Notice that &$passed? Here we pass the $passed variable by reference, so when it changes inside the closure, it will also change in our custom expectation.

Using this custom expectation, testing custom rules becomes easy. Let's see it in action.

it('will only accept fully uppercased values', function() {
    $rule = new UppercaseRule();

    expect($rule)->toPassWith('HELLO');

    // using not() you can test the inverse
    expect($rule)->not()->toPassWith('hello');

    // you can even chain expectations
    expect($rule)
        ->toPassWith('ANOTHER')
        ->toPassWith('TEST');
});

In a real-world test, you might want to add more cases to test this particular rule, but I hope this example makes it clear that toPassWith makes testing invokable rules very easy.

I particularly like that our test is just plain English using this syntax.

 expect($rule)->toPassWith('HELLO');

Cool, right?

If you want to use this expectation in your tests, you could opt to use our new spatie/pest-expectations package, which contains a couple of handy, opinionated custom expectations.

Stay up to date with all things Laravel, PHP, and JavaScript.

Follow me on Twitter. I regularly tweet out programming tips, and what I myself have learned in ongoing projects.

Every month I send out a newsletter containing lots of interesting stuff for the modern PHP developer.

Expect quick tips & tricks, interesting tutorials, opinions and packages. Because I work with Laravel every day there is an emphasis on that framework.

Rest assured that I will only use your email address to send you the newsletter and will not use it for any other purposes.

Comments

What are your thoughts on "How to test Laravel's invokable rules"?

Comments powered by Laravel Comments
Want to join the conversation? Log in or create an account to post a comment.