Filament Faker is a utility library designed to streamline writing testing that use Filament resources, forms, blocks, and components content. This library assists in automatically generating mock data for your tests within the Filament ecosystem.
- Data Generation: Automatically generate test data for Filament resources, forms, blocks, and components.
- Factory Support: Utilize factory definitions for precise and accurate data generation.
- Mutations: Modify specific component values to suit your testing scenarios.
- Configurable: Control the behavior of data generation using configuration options.
- Seamless Integration: Easily integrate the library into your Filament-based projects.
- Filament v3 or higher.
- PHP 8.1 or higher.
You can install the package via composer:
composer require joshbonnick/filament-faker --devYou can publish the config file with:
php artisan vendor:publish --tag="filament-faker-config"Call the fake method on a resource to retrieve an array of fields filled with fake data.
<?php
$data = PostResource::fake();Generated Data Example
[
"title" => "Hello World",
"slug" => "hello-world",
"meta-description" => "Ut voluptas molestiae sint repudiandae sint et quis.",
"content" => [
[
"type" => "App\Filament\Blocks\Heading",
"data" => [
"content" => "Impedit ex odio nostrum.",
"level" => "h5",
],
],
[
"type" => "App\Filament\Blocks\RichEditor",
"data" => [
"content" => "<p>Non est molestiae et quia reiciendis et iste.</p>",
],
],
[
"type" => "App\Filament\Blocks\Image",
"data" => [
"file" => "https://placehold.co/600x400.png",
"alt" => "Et nam aut nobis alias possimus voluptatem.",
],
],
],
"status" => "draft",
"categories" => [2],
]You can use the faked data in your tests.
<?php
namespace Tests\Feature\Filament\Blog;
use App\Enums\PostStatus;
use App\Filament\Resources\Blog\PostResource;
use App\Models\Category;
use App\Models\Post;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Livewire\Livewire;
use PHPUnit\Framework\Attributes\Test;
use Tests\FilamentTestCase;
class PostCreateTest extends FilamentTestCase
{
use RefreshDatabase;
#[Test]
public function it_can_create_posts(): void
{
Category::factory()->count(2)->create();
$data = PostResource::faker()->fake();
Livewire::test(PostResource\Pages\CreatePost::class)
->fillForm($data)
->call('create')
->assertHasNoFormErrors();
$this->assertDatabaseHas(Post::class, $data);
}
}If you have added a plugin such
as Spatie Media Library,
which adds the SpatieMediaLibraryFileUpload component you can register it in config/filament-faker.php like so:
<?php
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;
return [
'fakes' => [
SpatieMediaLibraryFileUpload::class => fn (SpatieMediaLibraryFileUpload $component) => fake()->imageUrl(),
],
];If you do not register extra components, the default callback will be used which returns the result of
fake()->sentence().
You may also override the default faker method attached to built in components by adding them to the config.
If you need to control a specific components value, you can chain mutateFake onto the fake builder. If this method
returns
null for a component then it will be ignored and filled by other methods.
<?php
use Filament\Forms\Components\Field;
use Illuminate\Support\Str;
use App\Services\InjectableService;
$data = PostResource::faker()->mutateFake(function (Field $component, InjectableService $service): mixed {
return match ($component->getName()) {
'title' => fake()->jobTitle(),
default => null,
};
});Alternatively you can add a mutateFake method to your Form, Block or Resource.
The closure passed to mutateFake supports dependency injection, you just need to type
hint \Filament\Forms\Components\Field
or the specific component type (e.g. \Filament\Forms\Components\TextInput) to get an instance of the component.
<?php
namespace App\Filament\Components;
use Filament\Forms\Components\Field;
use Filament\Forms\Components\TextInput;
use App\Services\InjectableService;
class MutatedComponent extends TextInput
{
public function mutateFake(Field $component, InjectableService $service): string
{
return $service->getSomething();
}
}By default, component names are used to map to a Faker method for more accurate data. There are several ways to disable this behavior:
Set use_component_names_for_fake to false in config/filament-faker.php which will disable the behavior for
the entire package as default.
You can chain shouldFakeUsingComponentName on the Faker API to disable the feature per test.
<?php
$data = PostResource::faker()->shouldFakeUsingComponentName(false)->fake();
// or
$data = PostResource::faker()->getForm()->shouldFakeUsingComponentName(false)->fake();
// or
$data = MyCustomBlock::faker()->shouldFakeUsingComponentName(false)->fake();If you need increased accuracy for a specific test then you can enable the usage of Factories. When the use of factories is enabled the generated data will be generated using definitions from the factory provided.
If no factory is provided the package will attempt to resolve one from the given resource, form, component or block.
As this feature executes Factory::makeOne under the hood, I recommend only using it in tests where the accuracy of the
faked
data is of significant importance.
<?php
namespace Tests\Feature\Services\ContentFormatting;
use App\Contracts\ContentFormatter;
use App\Filament\Resources\PostResource;
use Tests\TestCase;
class FormatBlocksTest extends TestCase
{
public function test_it_formats_blocks()
{
$data = PostResource::faker()->withFactory()->fake();
$service = app(ContentFormatter::class);
$content = $service->format($data);
// Make assertions of your formatted content...
}
}If you need to specify a factory you can pass a class-string or instance of a Factory to the withFactory() method.
Only Resources can resolve a factory automatically, if you wish to use a factory with a Block or Component, you must
provide
either the factory to withFactory or provide the model to the Component, Form or Block.
If you want to select only a specific set of definitions from your factory you can pass an array as to
the withFactory() method
which lists the definitions you want you use.
$data = PostResource::faker()->withFactory(onlyAttributes: ['title', 'slug'])->fake();If you only need a specific field or fields, you can specify them with the onlyFields method on Resource and Form
fakers.
$data = PostResource::faker()->onlyFields('title', 'slug', 'published_at')->fake();As this package adds methods using Laravel's Macroable trait, your IDE will not find the methods on its own. To fix
this you will need
to use the ide-helper package.
Please see CHANGELOG for more information on what has changed recently.
The MIT License (MIT). Please see License File for more information.