Forked this package to allow a few things:
- NOT fake Eloquen Model Events when usung EventFake: The idea, by convention, is to only use Model Events to "fix" basic stuff on Models, not trigger side effects, that should be done with specific Event Classes. For example, you could have a user_id and user_name column you want to sync upon save, or to ensure a default value or an important relation is set on save/update when referential integrity is not implemented in the DB. You - usually - want those to still occur when faking Events. But you don't want to trigger an Email notification or a Job to be queued
- While we're at it, do not fake spatie/laravel-state package StateChanged Events for the same reasons. Reserv listening to those for "coherence/integrity" and low-level reasons, then dispatch specific Events for side-efects
- Also, hopefully add more Fakes/Mocks as closure serialization appears to be coming/supported on laravel 9?
- Then, make those fake / don't fake exceptions configurable, bakcward compatible... and make a PR to the repo. ;-)
When running browser tests with Laravel Dusk, it is not possible to mock facades like it is usually done for http tests. This package aims to provide that functionality. However, it does so by doing some workarounds. It is recommended to read the Disclaimer (and in particular the Limitations) before using it.
Before adding it to your project, you can also give it a try with a bare-bones Laravel application prepared with tests running on a CI environment here: laravel-dusk-mocking-sandbox.
Install using composer:
composer require --dev noeldemartin/laravel-dusk-mocking
Add the following code to your base test case (usually DuskTestCase).
use NoelDeMartin\LaravelDusk\Browser;
...
protected function newBrowser($driver)
{
return new Browser($driver);
}The conceptual usage is the same as can be learned on Laravel's documentation about mocking. The only difference is that in Dusk, mocking can be set up independently on each browser instance. For that reason, instead of calling static methods we will call instance methods. Look at the following example on how to mock the Mail facade:
public function testOrderShipping()
{
$this->browse(function ($browser) use ($user) {
$mail = $browser->fake(Mail::class);
$browser->visit('...')
// Perform order shipping...
->assertSee('Order purchased! Check your email for details!');
$mail->assertSent(OrderShipped::class, function ($mail) use ($order) {
return $mail->order->id === $order->id;
});
// Assert a message was sent to the given users...
$mail->assertSent(OrderShipped::class, function ($mail) use ($user) {
return $mail->hasTo($user->email) &&
$mail->hasCc('...') &&
$mail->hasBcc('...');
});
// Assert a mailable was sent twice...
$mail->assertSent(OrderShipped::class, 2);
// Assert a mailable was not sent...
$mail->assertNotSent(AnotherMailable::class);
});
}Notice how the api is the same as Http tests.
Drivers serialize mocking data through requests, and cookies are used by default. The drawback is that using cookies, there is a size limit for how much information can be stored (4KB). For that reason, different drivers can be configured. Create a file named dusk-mocking.php inside your application config folder to change the default driver:
<?php
return [
/*
|--------------------------------------------------------------------------
| Default Driver
|--------------------------------------------------------------------------
|
| This option controls the default driver for storing mock data.
|
| Supported: "cookies", "session"
|
*/
'driver' => 'session',
];As explained below, each test may send multiple requests to the application to serialize/deserialize fakes. In order to prevent changing the state of the browser, this is done using javascript XHR requests. These requests will timeout in 1 second by default, but this can be configured using the $javascriptRequestsTimeout variable:
protected function newBrowser($driver)
{
Browser::$javascriptRequestsTimeout = 5;
return new Browser($driver);
}Doing this, only the functionality analogous of calling fake is available, and not methods mocking. In order to mock custom facades or modify Laravel's default fakes, the system can be extended by using custom fakes. Those can be registered in two ways:
- Registered globally (every test using fakes will use them). Add the following to your base test case (usually
DuskTestCase):
public function setUp()
{
parent::setUp();
// Register fake mocks
Mocking::registerFake(Mail::class, MyMailFake::class);
}- Another option is to register them only for one browser. This can be useful if it's necessary to have different fakes for multiple browsers or for aesthetic reasons (performance is not affected either way):
$this->browse(function (Browser $browser) {
$browser->registerFake(Mail::class, MyMailFake::class);
$mail = $browser->mock(Mail::class);
// Proceed with the test
});In order to understand how to implement these Fake classes, you can take a look at how Laravel fakes are implemented, since those are the ones used by default. This classes can also be used as a base, extending them and adding any modifications.
Most scenarios should be covered with http tests, since they both run faster and are more reliable when testing your code. The same could be said when testing your frontend and Javascript, there are multiple frameworks specific for that. However, there is definitely some value on using Dusk for integration & end to end tests. For those scenarios it's rarely necessary to mock any facades. But if you do find yourself in that situation, this package can help you 😃.
The reason why mocking cannot be done like in normal http tests is because when Dusk runs a test it's really doing an actual request using a browser (running for example on chromedriver). Server and client don't share the same runtime, and that's why it isn't possible to have code communicate between them. Knowing this, how does this package work? Well, Dusk is already achieving something similar to this when using authentication. Some special routes (as a convention starting with _dusk) are created to provide communication with the server process, and state is persisted in the session like it would with a normal Laravel session. Given this and other uses, different drivers can be configured for tests (in your .env.dusk or phpunit.dusk.xml files). By using a separate session driver such as a testing database, it can be wiped out before and after each test to guarantee a real black-box scenario.
In a nutshell, what happens under the hood is that Facades are replaced using the swap method at the beginning of every request, and they'll be serialized at the end. When calling assertions methods from test code, data will be deserialized into the test runtime and assertions executed as usual.
You can learn more about how this works looking at MockingProxy, Driver and MockingServiceProvider classes.
The serialization/deserialization of mocked services is implemented using php's serialize and unserialize functions. One limitation that this ensues is that closures can't be serialized. If you see an error saying Serialization of 'Closure' is not allowed, that means somewhere inside a service you're faking, there is a closure.
There is a couple of things you could do to work around this limitation.
If you have control over the service, you could use the SerializableClosure class to make your closures serializable (Laravel core is already doing this in multiple places).
If you're trying to mock a 3rd party service you don't have control over, you could implement a service fake yourself instead of using the built-in class. This library already does it with some common Laravel services, but it doesn't cover the complete Laravel api. You can register your custom fakes using the extending functionality. Although this may seem a daunting task, keep in mind that you only need to implement fakes for the functionality you're testing using this package. And as we discussed at the start of this section, that shouldn't be a lot.