DEV Community: Eduardo Guzmán

Tips for testing queued jobs in Laravel

Eduardo Guzmán — Thu, 19 Sep 2024 13:53:01 +0000

When working with Laravel applications, it’s common to encounter scenarios where a command needs to perform an expensive task. To avoid blocking the main process, you might decide to offload the task to a job that can be processed by a queue.

Let’s walk through an example. Imagine the command app:import-users needs to read a large CSV file and create a user for each entry. Here’s what the command might look like:

/* ImportUsersCommand.php */

namespace App\Console\Commands;

/*...*/

class ImportUsersCommand extends Command
{
    protected $signature = 'app:import-users';

    public function handle()
    {
        dispatch(new ImportUsersJob());

        $this->line('Users imported successfully.');
        $this->line('There are: ' . User::count(). ' Users.');
    }
}

In this example, the command dispatches a job to handle the reading of the file and the creation of users. Here’s how the ImportUsersJob.php might look:

/* ImportUsersJob.php */

namespace App\Jobs;

/*...*/

class ImportUsersJob implements ShouldQueue
{
    public function handle(FileReader $reader): void
    {   
        foreach($reader->read('users.csv') as $data) {
            User::create([
                'name' => $data['name'], 
                'email' => $data['email'],
            ]);
        }
    }
}

When testing this feature, a typical test for the command might look like this:

/* ImportUsersCommandTest.php */

namespace Tests\Feature;

/*...*/

class ImportUsersCommandTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_processes_the_file(): void
    {
        Storage::fake('local')->put('users.csv', "...");

        $this->artisan('app:import-users')
            ->expectsOutput('Users imported successfully.')
            ->expectsOutput('There are: 10 Users.')
            ->assertSuccessful();

        $this->assertDatabaseCount('users', 10);
    }
}

At first glance, this test seems to work perfectly. Running the test suite shows a successful result:

Real World Execution

However, when you run the app:import-users command in a real environment, you might get an unexpected result:

As you can see, the command output indicates that there are 0 users in the database. So, Why does this happen?

The reason is that the job is dispatched to a queue, so it doesn’t run synchronously with the command execution. The users will be created only when the queue processes the job later.

Why does the test pass?

The test suite uses the sync queue driver by default, meaning jobs are processed synchronously during the test. As a result, the job runs immediately, giving the idea that everything works as expected.

While this behavior is acceptable in the test environment, it’s important to recognize that real-world results depend on the QUEUE_CONNECTION configuration in your production environment. And given your project requirements, you might know that the job will be processed in an async queue.

Once you’re aware of this distinction, you may want to improve your tests to avoid “false positives”.

Testing your job is dispatched

First, it’s important to verify that the command actually dispatches the job, regardless of whether the job is processed synchronously or asynchronously. Here’s how to test that:

/* ImportUsersCommandTest.php */

namespace Tests\Feature;

/*...*/

class ImportUsersCommandTest extends TestCase
{    
    public function test_it_dispatches_the_job(): void
    {
        Queue:fake();

        $this->artisan('app:import-users')
            ->expectsOutput('Process has been queued.')
            ->assertSuccessful();

        Queue::assertPushed(ImportUsersJob::class);
    }
}

Testing your job is processed

Once you’ve confirmed that the job is dispatched, you can test the actual work performed by the job in a separate test. Here’s how you might structure the test for the job:

/* ImportUsersJobTest.php */

namespace Tests\Feature;

/*...*/

class ImportUsersJobTest extends TestCase
{
    use refreshDatabase;

    public function test_it_processes_the_file()
    {
        Storage::fake('local')->put('users.csv', "...");

        app()->call([new ImportUsersJob(), 'handle']);

        $this->assertDatabaseCount('users', 10);
    }
}

This ensures that the job performs the necessary work, regardless of whether it’s processed by a queue or synchronously.

Handling edge cases

As in real life, edge cases might happen and you should be ready for these.

Laravel’s queue system, according to your workers configuration, will retry jobs when an exception occurs, and if retries are exceeded, the job will be marked as failed.

So, what happens if the file doesn’t exist? You need to handle such edge cases by validating inputs and throwing exceptions when necessary.

Here’s how you might handle this in your job:

/* ImportUsersJobTest.php */

namespace App\Jobs;

/*...*/

class ImportUsersJob implements ShouldQueue
{
    use Queueable;

    public function handle(FileReader $reader): void
    {   
        if(!Storage::disk('local')->exists('users.csv')){
            throw new Exception('The users.csv file doesn\'t exist.')
        }

        foreach($reader->read('users.csv') as $data) {
            User::create([
                'name' => $data['name'], 
                'email' => $data['email'],
            ]);
        }
    }
}

Here’s how you’d test this scenario:

/* ImportUsersJobTest.php */

namespace Tests\Feature;

/*...*/

class ImportUsersJobTest extends TestCase
{
    use refreshDatabase;

    /*...*/

    public function test_it_fails_when_file_doesnt_exist(): void
    {
        Storage::fake('local');

        $this->expectException(Exception::class);
        $this->expectExceptionMessage('The users.csv file doesn\'t exist.');

        dispatch(new ImportUsersJob());
    }
}

Final thoughts

This approach ensures that your tests more accurately reflect how jobs will be processed in the real world.
The same strategy can be applied when a controller dispatches a job to a queue or where a event listener is queued.
As always, adjust these practices to fit your project and team.

I’d love to hear your thoughts!

Adding Quill Editor to a Livewire-Alpine.js App

Eduardo Guzmán — Sat, 13 Jun 2020 19:12:50 +0000

In case you are not familiar with the stack, this is a little tech reference:

Livewire - Livewire is a full-stack framework for Laravel that takes the pain out of building dynamic UIs.
Alpine.js - Alpine.js is a rugged, minimal framework for composing JavaScript behavior in your markup.
Quill - Quill is a modern WYSIWYG editor built for compatibility and extensibility.

Using third party libraries in Livewire is a very common use case. This time I faced the need to add a WYSIWYG editor and wanted to show how it can be achieved.

The very short response is shown in this snippet. Next, I will break down every piece.

This is how your Livewire component will look like.

<!-- livewire/edit-component.blade.php -->
@push('styles')
    <link href="https://cdn.quilljs.com/1.3.6/quill.snow.css" rel="stylesheet">
@endpush

@push('scripts')
    <script src="https://cdn.quilljs.com/1.3.6/quill.js"></script>
@endpush

<div class="mt-2 bg-white" wire:ignore>
  <div
       x-data
       x-ref="quillEditor"
       x-init="
         quill = new Quill($refs.quillEditor, {theme: 'snow'});
         quill.on('text-change', function () {
           $dispatch('input', quill.root.innerHTML);
         });
       "
       wire:model.debounce.2000ms="description"
  >
    {!! $description !!}
  </div>
</div>

Now, let's break down the pieces that are working here.

In order to use Quill we need to import the library into our webpage. We use a CDN that will provide the css and the js that is required.
We are adding the <link> and <script> tags by using laravel blade stacks.

<!-- layouts/base.blade.php -->
<html>
  <head>
    @stack('styles')
  </head>
  <body>
    @stack('scripts')
  </body>
</html>

<!-- livewire/edit-component.blade.php -->
@push('styles')
  <link href="https://cdn.quilljs.com/1.3.6/quill.snow.css" rel="stylesheet">
@endpush

@push('scripts')
  <script src="https://cdn.quilljs.com/1.3.6/quill.js"></script>
@endpush

Next, add a <div> element in which we will be mounting Quill. Alpine.js will be used to mount the Editor into this element.

x-data will tell Alpine.js to declare a new component scope in this element, this way we can use other Alpine.js features.

x-ref=quillEditor will let us reference this DOM element in a very convenient way. We will be able to use $refs.quillEditor later when we need to reference this element.

x-init= will tell Apline.js to run an expression when this component is initialized. That is why we added the x-data on that component.

At this point we can already use Quill, we will initialize it and add its event handler.

First, we create a new instance of Quill and use the $ref.quillEditor to bind the editor into this Element.

Then, we use the same instance and add an event handler to it. The event handler will listen to the text-change event. When this event happens, we will fetch the HTML that has been added to the editor and by using Alpine.js's $dispatch feature, we will emit an input event in this component.

<div
  ...
  x-init="
    quill = new Quill($refs.quillEditor, {theme: 'snow'});

    quill.on('text-change', function () {
      $dispatch('input', quill.root.innerHTML);
    });
  "
>...</div>

wire:model.debounce.3000ms="description". Given that we are now reproducing an input event, we can use Livewires data binding feature. Addingwire:model="description"` will bind the value of the Quill editor right into our Livewire component. This way we can have this data in our Laravel app.

Adding debounce.2000ms to the data binding will debounce these many input events and update the value of the property after 2000 ms.

wire:ignore Adding this to a parent element will tell Livewire to skip DOM-diffing for this element, this is useful because Quill adds elements that Livewire does not know from the original HTML. This will prevent a small page flicker when re-rendering Livewire components.

Closing

That's it, very easy and right into your HTML Markup.

The same approach will work with many other third party libraries.

Enjoy the Livewire - AlpineJs Stack.

Share your tailwindcss theme with the world

Eduardo Guzmán — Sat, 23 Nov 2019 20:45:35 +0000

Tailwind CSS, the utility first css framework, comes with an amazing default theme that works very well with most of the designs you need to make, but you might want to tweak it a little bit. Changing colors, for example, is one of the most common uses I have found when working with tailwindcss.

Once you have your custom configuration you may want to share it with your team or with the world. Imagine sharing the colors of your company brand, or your new design system. This is now possible with tailwindcss.

Create a tailwindcss plugin

First, create a new file and give it a name. I will use acme-design-system.js as an example:

module.exports = {
    config: {
        //
    },
    handler: function() {
        //
    }
}

This is how you can define a tailwindcss plugin using an object. Inside the config key you can define your own settings, overwrite the default settings or extend the default settings. In this case we will extend the defaults.

module.exports = {
    config: {
        theme: {
            extend: {
                colors:
                    primary: {
                        900: '#055324',
                        800: '#18672B',
                        700: '#298538',
                        600: '#3BA444',
                        500: '#4DBB4E',
                        400: '#6ED36A',
                        300: '#A2E69A',
                        200: '#CBF4C4',
                        100: '#F0FCED',
                    },
                }
            }
        }     
    },

    handler: function({ addUtilities, addComponents}) {
        addUtilities(...);
        addComponents(...);
    }
}

In this example I am adding a new set of colors named primary, and tailwindcss will generate new utilities based on this color. Also, I could add some utilities or components that will be part of the design system.

Require the plugin

Now, you can make use of your plugin. In your tailwind.config.js file, require the plugin file in the plugins section.

module.exports = {
    theme: {
        ...
    },
    plugins: [
        require('acme-design-system.js'),
    ]
};

Then, the plugin will be used whenever you process your tailwindcss config.

Share with the world

Given that a plugin is just a file (acme-design-system.js), you can choose the channel you want to use to share this file, and the way you want to keep it updated.

My choice was to make a npm package and publish it in npm.js. You can see that it is very easy, just by following some simple steps.

Closing

Plugins are not a new thing on tailwindcss, but this new syntax is very useful when working with configuration keys.

Tailwindcss plugins allow many possibilities to extend the framework; this is just one of them.

You can see the package I published in placetopay-org/flate, it is still a work in progress but was designed to fit our needs, and I wanted to share it with you.

Share your thoughts.

Exception Factories for better code

Eduardo Guzmán — Wed, 11 Sep 2019 15:43:07 +0000

Yes, Exception factories... Although I think it has been shared many times over the web. Today, I was making a code review and found out a good use case for "Exception Factories", so I think it is worth it to share this programming tip with you.

The code I was reviewing had somewhere in a method this:

public function user(){
    ...

    $token = $this->getToken();
    $siteCredential = $this->getSiteCredential();

    throw_if(empty($token),
        AuthenticationException::class,
        __('auth.failed', ['code' => AuthenticationCodes::TOKEN_NOT_PROVIDED]), 401);

    throw_if(is_null($siteCredential),
        AuthenticationException::class,
        __('auth.failed', ['code' => AuthenticationCodes::CREDENTIALS_NOT_FOUND]), 401);

    throw_if($siteCredential->hasExpired(),
        AuthenticationException::class,
        __('auth.failed', ['code' => AuthenticationCodes::CREDENTIALS_EXPIRED]), 401);

    throw_if(! optional($siteCredential->site)->isEnabled(),
        AuthenticationException::class,
        __('auth.failed', ['code' => AuthenticationCodes::SITE_DISABLED]), 401);
    ...
}

The code works fine, don't get me wrong about this, the thing I am trying to achieve with this refactor is to make this code a bit more readable and clean. As you can see each Exception is conditionally thrown making use of a multiline expression in php, these long expressions might become not so eye-friendly when reading code.

Whenever I reach situations like this, I like to refactor them into "Exception Factory Methods". We can see that every thrown exception is an AuthenticationException so it makes sense to work inside the class itself, we will introduce one (or many) new static methods that will handle the "construction" of the exception.

After refactoring, the AuthenticationException class looks like this:

class AuthenticationException extends Exception
{
    protected $httpStatusCode = 401;

    public static function forCode(string $code): self
    {
        return new self(__('auth.failed', ['code' => $code]));
    }

    public static function forTokenNotFound(): self
    {
        return self::forCode(AuthenticationCodes::TOKEN_NOT_PROVIDED);
    }

    public static function forCredentialsNotFound(): self
    {
        return self::forCode(AuthenticationCodes::CREDENTIALS_NOT_FOUND);
    }

    public static function forCredentialsExpired(): self
    {
        return self::forCode(AuthenticationCodes::CREDENTIALS_EXPIRED);
    }

    public static function forSiteDisabled(): self
    {
        return self::forCode(AuthenticationCodes::SITE_DISABLED);
    }

Now we can clean up our initial user() method to use our factory methods:

public function user(){
    ...

    $token = $this->getToken();
    $siteCredential = $this->getSiteCredential();

    if (empty($token)) {
        throw AuthenticationException::forTokenNotFound();
    }

    if (is_null($siteCredential)) {
        throw AuthenticationException::forCredentialsNotFound();
    }

    if ($siteCredential->hasExpired()) {
        throw AuthenticationException::forCredentialsExpired();
    }

    if (is_null($siteCredential->site) || $siteCredential->site->isDisabled()) {
        throw AuthenticationException::forSiteDisabled();
    }
    ...
}

I think it makes the code a little bit more expressive and readable.

Share what you think!!