Sevalla is the all-in-one PaaS for your web projects. Host and deploy your applications, databases, object storage, and static sites. Enjoy advanced deployment pipelines, a complete database studio, instant preview apps, and one-click templates. The pricing is simple: no hidden fees, no seat-based pricing, and you pay only for what you use. Get real human support from developers.

Get started now with a $50 credit at Sevalla.com.

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.

You can follow me on these platforms:

On all these platforms, regularly share 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.