You rerun the pipeline.
Now everything is green.

You change absolutely nothing.
An hour later, another random failure appears.

If this sounds familiar, you are probably dealing with flaky tests.

Flaky tests are tests that sometimes pass and sometimes fail without any meaningful code changes. They are one of the most frustrating problems in modern software development because they slowly destroy trust in your test suite.

And once developers stop trusting tests, they start ignoring failures, rerunning pipelines blindly, and eventually shipping bugs to production.

After dealing with flaky tests in multiple Laravel projects, I noticed something important:

Most flaky tests are not caused by PHPUnit itself.

They are usually caused by hidden shared state, timing assumptions, asynchronous behavior, or infrastructure leaking between tests.

In this article, I’ll show the most common causes of flaky tests in Laravel and how to fix them properly.

Previous article in Testing category: https://codecraftdiary.com/2026/05/09/how-mutation-testing-exposes-the-truth-php-2026-edition/

What Makes a Test “Flaky”?

A flaky test has three characteristics:

• It fails inconsistently
• The failure is difficult to reproduce
• Rerunning the test often “fixes” it

This is different from a normal failing test.

A normal failing test indicates a deterministic bug.

A flaky test creates uncertainty.

And uncertainty is dangerous in CI pipelines because developers eventually stop taking failures seriously.

1. Time-Dependent Tests

One of the most common sources of flaky tests is time.

Laravel makes working with time easy through Carbon, but time-based logic can easily become unstable.

Consider this example:

public function test_subscription_expires_after_24_hours(): void
{
    $subscription = Subscription::factory()->create([
        'expires_at' => now()->addDay(),
    ]);

    sleep(1);

    $this->assertFalse($subscription->isExpired());
}

public function test_subscription_expires_after_24_hours(): void
{
    $subscription = Subscription::factory()->create([
        'expires_at' => now()->addDay(),
    ]);

    sleep(1);

    $this->assertFalse($subscription->isExpired());
}

This test may pass most of the time.

But depending on:

• CI speed
• server load
• execution timing
• timezone handling

it can eventually fail unpredictably.

The fix is simple:

Use fixed time.

Carbon::setTestNow('2026-05-28 10:00:00');

$subscription = Subscription::factory()->create([
    'expires_at' => now()->addDay(),
]);

$this->assertFalse($subscription->isExpired());

Carbon::setTestNow('2026-05-28 10:00:00');

$subscription = Subscription::factory()->create([
    'expires_at' => now()->addDay(),
]);

$this->assertFalse($subscription->isExpired());

And always clean up afterwards:

Carbon::setTestNow();

Carbon::setTestNow();

Without cleanup, fake time can leak into other tests and create even more randomness.

2. Shared Database State

Another massive source of flaky tests is database leakage between tests.

I still see projects where tests depend on records created by previous tests.

Example:

public function test_user_can_create_post(): void
{
    $this->post('/posts', [
        'title' => 'Example',
    ]);

    $this->assertDatabaseCount('posts', 1);
}

public function test_user_can_create_post(): void
{
    $this->post('/posts', [
        'title' => 'Example',
    ]);

    $this->assertDatabaseCount('posts', 1);
}

At first, this looks harmless. However, once another test inserts posts into the database, the count may suddenly become 2, 5, or even 12.

The fix is proper database isolation.

In Laravel, this usually means:

use RefreshDatabase;

use RefreshDatabase;

or:

use DatabaseTransactions;

use DatabaseTransactions;

depending on your architecture.

I already wrote an entire article comparing these approaches because using the wrong one can create hidden instability.

The important part is this:

Tests should never depend on leftovers from previous tests.

Ever.

3. Random Factories

Factories are great.

Randomness is not.

This test looks innocent:

$user = User::factory()->create();

$this->assertEquals('admin', $user->role);

$user = User::factory()->create();

$this->assertEquals('admin', $user->role);

But if the factory generates random roles, this test becomes unstable immediately.

I’ve seen this problem especially in large Laravel projects where factories evolved over years and slowly accumulated randomness everywhere.

Instead, explicitly define required state:

$user = User::factory()->create([
    'role' => 'admin',
]);

$user = User::factory()->create([
    'role' => 'admin',
]);

Deterministic data creates deterministic tests.

4. Queue and Async Problems

Queues are one of the biggest sources of flaky behavior.

Especially when developers partially fake queues while still allowing some jobs to execute asynchronously.

Example:

Queue::fake();

dispatch(new SendInvoiceJob($invoice));

$this->assertDatabaseHas('invoices', [
    'status' => 'sent',
]);

Queue::fake();

dispatch(new SendInvoiceJob($invoice));

$this->assertDatabaseHas('invoices', [
    'status' => 'sent',
]);

This can fail because the queued job never actually runs.

Or worse:
it runs sometimes depending on environment configuration.

Another common issue is testing behavior immediately after dispatching async jobs.

Example:

dispatch(new SyncProductsJob());

$this->assertDatabaseCount('products', 500);

dispatch(new SyncProductsJob());

$this->assertDatabaseCount('products', 500);

The assertion may execute before the worker finishes.

Locally it passes.

In CI it randomly fails.

A better approach is either:

• testing the dispatch itself,
• or running jobs synchronously during tests.

Example:

Bus::fake();

dispatch(new SyncProductsJob());

Bus::assertDispatched(SyncProductsJob::class);

Bus::fake();

dispatch(new SyncProductsJob());

Bus::assertDispatched(SyncProductsJob::class);

Or:

config()->set('queue.default', 'sync');

config()->set('queue.default', 'sync');

during the test environment.

5. Parallel Testing Issues

Parallel testing speeds up CI dramatically. However, it also exposes hidden shared state.

I’ve seen failures caused by:

• shared Redis keys
• shared files
• cached config
• temporary directories
• static variables
• singleton state

Example:

Storage::disk('local')->put('report.pdf', 'content');

Storage::disk('local')->put('report.pdf', 'content');

If multiple tests write the same file simultaneously, random failures appear.

The fix is isolation.

Example:

Storage::fake();

Storage::fake();

or unique filenames:

$file = Str::uuid() . '.pdf';

$file = Str::uuid() . '.pdf';

Parallel testing does not create flaky tests.

It reveals problems that already existed.

6. External APIs

Real HTTP calls inside tests are dangerous.

Sometimes the API is slow.

Sometimes rate limits trigger.

Sometimes sandbox environments fail.

And suddenly your test suite becomes unreliable for reasons completely outside your application.

This is why external APIs should usually be mocked or faked.

Laravel provides excellent HTTP faking:

Http::fake([
    '*' => Http::response([
        'success' => true,
    ], 200),
]);

Http::fake([
    '*' => Http::response([
        'success' => true,
    ], 200),
]);

Now your tests become:

• faster
• deterministic
• independent from network stability

I covered this topic in more detail in my API mocking article because external integrations are one of the easiest ways to accidentally create unstable tests.

7. Tests That Depend on Execution Order

This one is extremely dangerous.

A test passes only because another test ran before it.

Example:

public function test_admin_exists(): void
{
    $this->assertDatabaseHas('users', [
        'email' => 'admin@example.com',
    ]);
}

public function test_admin_exists(): void
{
    $this->assertDatabaseHas('users', [
        'email' => 'admin@example.com',
    ]);
}

This silently depends on another test creating the admin user first.

Run tests individually and this suddenly fails.

A good test should work:

• independently
• repeatedly
• in any order

If execution order matters, the suite is fragile.

Why Flaky Tests Become Expensive

The biggest problem with flaky tests is not technical.

It is psychological.

Once developers stop trusting CI:

• failures get ignored
• reruns become normal
• real bugs get missed
• confidence disappears

I’ve seen teams where developers reran pipelines three or four times automatically because “CI is always flaky anyway.”

That is dangerous.

Because eventually a real regression hides inside the noise.

Final Thoughts

Flaky tests are rarely random.

There is almost always an underlying engineering problem:

• shared state
• uncontrolled time
• async behavior
• non-isolated infrastructure
• hidden dependencies

The solution is not “rerun CI.”

The solution is making tests deterministic.

A reliable test suite should produce the same result every time:

• locally
• in CI
• on every machine
• under every execution order

Once your tests become deterministic, your entire development workflow becomes faster, safer, and dramatically less frustrating.

The post Flaky Tests in Laravel: Why Your CI Randomly Fails appeared first on CodeCraft Diary.

• Pending
• Paid
• Shipped
• Cancelled

When PHP introduced native Enums, they became the perfect fit for this kind of state modeling. They are type-safe, database-friendly, and much cleaner than arbitrary strings spread across the codebase.

For simple workflows, Enums are often exactly the right solution. The problem begins when states stop being just labels and start accumulating behavior.

This article explores where Enums work well, where they start breaking down, and how the State Pattern can help without introducing unnecessary complexity or framework-heavy abstractions.

Previous articlet in Refactoring cattegory: https://codecraftdiary.com/2026/05/02/mastering-value-objects-in-php/

Enums Are Excellent — Until They Aren’t

For simple workflows, Enums are clean and maintainable.

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

This is ideal when states are primarily used for:

• Filtering and querying data
• Display logic and badges in UI
• Basic validation
• API serialization
• Database persistence

Problems start appearing when business rules become state-dependent. A common first step is adding helper methods directly into the Enum:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function canBeCancelled(): bool
    {
        return match($this) {
            self::Pending, self::Paid => true,
            self::Shipped, self::Cancelled => false,
        };
    }
}

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function canBeCancelled(): bool
    {
        return match($this) {
            self::Pending, self::Paid => true,
            self::Shipped, self::Cancelled => false,
        };
    }
}

This is still perfectly reasonable and respects the KISS principle.

But over time, workflows tend to evolve. A cancellation process may eventually require refunding payments, restocking inventory, notifying external systems, creating audit logs, or dispatching events.

At that point, the Enum slowly stops being a simple value object and starts becoming a workflow engine.

The Hidden Problem: Growing Coupling

Consider how a bloating Enum typically looks in production:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function cancel(
        Order $order,
        PaymentGateway $gateway,
        InventoryManager $inventory
    ): void {
        match ($this) {
            self::Pending => $order->updateStatus(self::Cancelled),

            self::Paid => $this->executeCancellationWithRefund($order, $gateway, $inventory),

            self::Shipped => throw new LogicException('Cannot cancel a shipped order.'),
            self::Cancelled => throw new LogicException('Order is already cancelled.'),
        };
    }

    private function executeCancellationWithRefund(Order $order, PaymentGateway $gateway, InventoryManager $inventory): void
    {
        $gateway->refund($order->payment_id);
        $inventory->restock($order->items);
        $order->updateStatus(self::Cancelled);
    }
}

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function cancel(
        Order $order,
        PaymentGateway $gateway,
        InventoryManager $inventory
    ): void {
        match ($this) {
            self::Pending => $order->updateStatus(self::Cancelled),

            self::Paid => $this->executeCancellationWithRefund($order, $gateway, $inventory),

            self::Shipped => throw new LogicException('Cannot cancel a shipped order.'),
            self::Cancelled => throw new LogicException('Order is already cancelled.'),
        };
    }

    private function executeCancellationWithRefund(Order $order, PaymentGateway $gateway, InventoryManager $inventory): void
    {
        $gateway->refund($order->payment_id);
        $inventory->restock($order->items);
        $order->updateStatus(self::Cancelled);
    }
}

The issue here is not the number of lines. The issue is coupling.

The Enum now knows about payment infrastructure, inventory management, business transitions, and side effects. Adding a new state such as PartiallyRefunded now requires modifying a growing conditional structure that centralizes unrelated responsibilities.

This is where applications experience state explosion—the point where transitions and side effects become increasingly difficult to isolate and reason about. At this stage, the code may still look “short,” but it is no longer simple.

The State Pattern: Isolating Behavior

The State Pattern addresses this by moving behavior into dedicated state objects. Instead of one large conditional structure, each state becomes responsible for its own transitions and rules.

1. Define the Workflow Contract

interface OrderState
{
    public function cancel(Order $order): void;
    public function ship(Order $order): void;
    public function toValue(): string;
}

interface OrderState
{
    public function cancel(Order $order): void;
    public function ship(Order $order): void;
    public function toValue(): string;
}

The interface should stay minimal. Only include operations whose behavior actually changes depending on the state.

2. Create Small, Focused State Classes

Each state becomes an isolated, testable component. Look at how clean the responsibilities become:

Pending State

readonly class PendingState implements OrderState
{
    public function cancel(Order $order): void
    {
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Cannot ship an unpaid order.');
    }

    public function toValue(): string
    {
        return 'pending';
    }
}

readonly class PendingState implements OrderState
{
    public function cancel(Order $order): void
    {
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Cannot ship an unpaid order.');
    }

    public function toValue(): string
    {
        return 'pending';
    }
}

Paid State

readonly class PaidState implements OrderState
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function cancel(Order $order): void
    {
        $this->gateway->refund($order->payment_id);
        $this->inventory->restock($order->items);
        
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        $order->transitionTo(new ShippedState());
    }

    public function toValue(): string
    {
        return 'paid';
    }
}

readonly class PaidState implements OrderState
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function cancel(Order $order): void
    {
        $this->gateway->refund($order->payment_id);
        $this->inventory->restock($order->items);
        
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        $order->transitionTo(new ShippedState());
    }

    public function toValue(): string
    {
        return 'paid';
    }
}

Shipped State

readonly class ShippedState implements OrderState
{
    public function cancel(Order $order): void
    {
        throw new LogicException('The order has already been shipped.');
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Order is already shipped.');
    }

    public function toValue(): string
    {
        return 'shipped';
    }
}

readonly class ShippedState implements OrderState
{
    public function cancel(Order $order): void
    {
        throw new LogicException('The order has already been shipped.');
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Order is already shipped.');
    }

    public function toValue(): string
    {
        return 'shipped';
    }
}

Most importantly, adding a new state no longer requires modifying a massive conditional block. This aligns naturally with the Open/Closed Principle.

3. A Pragmatic Hybrid Approach

Completely replacing Enums with raw state objects is often unnecessary in database-driven applications. In practice, the most maintainable approach is a hybrid architecture:

• Enums handle persistence, transport, and API serialization.
• State objects handle business behavior and side effects.

The Enum remains the canonical storage format:

enum OrderStatusEnum: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

enum OrderStatusEnum: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

Resolving State Behavior Cleanly

Instead of resolving dependencies directly inside the model, a dedicated factory keeps infrastructure concerns isolated from your domain.

readonly class OrderStateFactory
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function make(OrderStatusEnum $status): OrderState
    {
        return match ($status) {
            OrderStatusEnum::Pending => new PendingState(),
            OrderStatusEnum::Paid => new PaidState($this->gateway, $this->inventory),
            OrderStatusEnum::Shipped => new ShippedState(),
            OrderStatusEnum::Cancelled => new CancelledState(),
        };
    }
}

readonly class OrderStateFactory
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function make(OrderStatusEnum $status): OrderState
    {
        return match ($status) {
            OrderStatusEnum::Pending => new PendingState(),
            OrderStatusEnum::Paid => new PaidState($this->gateway, $this->inventory),
            OrderStatusEnum::Shipped => new ShippedState(),
            OrderStatusEnum::Cancelled => new CancelledState(),
        };
    }
}

Keeping the Model Lightweight

Now, the Order model stays clean and decoupled from infrastructure services. It simply orchestrates the workflow via the factory:

class Order
{
    public OrderStatusEnum $status;
    public int $payment_id;
    public array $items = [];

    public function __construct(
        private readonly OrderStateFactory $stateFactory,
    ) {}

    public function transitionTo(OrderState $state): void
    {
        $this->status = OrderStatusEnum::from($state->toValue());
    }

    public function cancel(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->cancel($this);
    }

    public function ship(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->ship($this);
    }
}

class Order
{
    public OrderStatusEnum $status;
    public int $payment_id;
    public array $items = [];

    public function __construct(
        private readonly OrderStateFactory $stateFactory,
    ) {}

    public function transitionTo(OrderState $state): void
    {
        $this->status = OrderStatusEnum::from($state->toValue());
    }

    public function cancel(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->cancel($this);
    }

    public function ship(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->ship($this);
    }
}

This keeps your persistence simple, business logic isolated, dependencies explicit, and workflows extensible—all without introducing heavy framework abstractions.

Testing Becomes Significantly Easier

One of the biggest advantages of state objects is test isolation. Instead of testing a large Enum with multiple branches and heavy mocking setups, each workflow state can be verified independently:

• PendingStateTest — Verify that cancellation transitions directly to cancelled.
• PaidStateTest — Assert that the payment gateway receives the refund call and inventory is restocked.
• ShippedStateTest — Assert that exceptions are thrown correctly on forbidden actions.

This dramatically reduces test setup complexity and makes transition rules much easier to verify.

When Should You Use Enums vs. State Objects?

Use Enums when:

• The state is primarily a static label.
• Transitions are simple and linear.
• Behavior differences between states are minimal.
• No external services or infrastructure are involved.
• Examples: Blog post status (Draft, Published), user visibility flags, or filtering categories.

Use the State Pattern when:

• Transitions trigger side effects or external APIs.
• States require completely different validation rules.
• Workflows keep expanding with new edge cases.
• Conditional logic (match or if/else) around the same state starts repeating across the codebase.
• Examples: Payment workflows, fulfillment systems, subscription lifecycles, or approval pipelines.

Final Thoughts

Enums are not the enemy. In fact, they are often the best solution for simple state representation.

The real problem starts when business workflows evolve and a single Enum begins accumulating infrastructure dependencies, transition orchestration, side effects, and validation logic. At that point, the issue is no longer code length—it is responsibility density.

The State Pattern is valuable not because it is “more advanced,” but because it isolates change. And in long-lived systems, isolated change is usually what keeps complexity manageable.

The post State Pattern vs. Enums in Modern PHP appeared first on CodeCraft Diary.

But how do you actually fix it? Knowing small PRs are better is easy. Changing a team’s habits is the hard part.
This is the practical roadmap for moving from long-lived branches to real trunk-based flow.

Previous posts about Trunk-Based Development: Pt. 2 –https://codecraftdiary.com/2026/04/29/trunk-based-development-your-pull-requests-are-still-too-big/

Pt. 1 https://codecraftdiary.com/2026/04/04/trunk-based-development-why-most-teams-think-they-use-it-but-dont/

Phase 1: Fixing the Foundation (The Infrastructure)

You cannot do trunk-based development with slow pipelines. If your CI/CD suite is a bottleneck, your developers will naturally revert to batching work to “save time”.

1. The 10-Minute Rule for CI

In 2026, speed is a requirement, not a luxury. If your CI takes 20 minutes, there is friction; if it takes 60 minutes, people stop merging frequently.

• Target: Aim for CI under 10 minutes.
• Action: Parallelize your test suites. If a test is flaky, don’t ignore it—fix it or delete it. A flaky test suite is a debt that destroys the confidence needed for frequent merges.

2. Radical Observability

To merge to main multiple times a day safely, you need to know exactly what is happening in production.

• Action: Implement real-time logging and alerting. If you merge a small change and the error rate spikes, you should know within seconds, not after a customer support ticket arrives.

Phase 2: Mastering the Tools of “Incomplete” Work

The biggest fear in TBD is merging work that isn’t “done”. To overcome this, you must decouple deployment from release.

3. Feature Flags as a Standard

Feature flags are the missing piece for most teams. They allow you to merge partial work and control exposure without waiting for the entire feature to be polished.

• The Strategy: Wrap new logic in a toggle. This lets the code live in the main branch, deployed to production but hidden from users until it’s ready.
• The Rule: A feature flag must exist from the start, not as an afterthought.

4. Branch by Abstraction for Large Changes

When you are doing a complete architectural overhaul, do not create a “v2-architecture” Git branch. That is a recipe for a merge nightmare.

• The Strategy: Keep both the old and new architectures in the main branch simultaneously.
• The Execution: Use an abstraction layer (an interface or wrapper) to toggle between the old and new logic. Run “dark launches” where the new code executes, but you ignore the results or simply compare them against the old version to gain confidence.

Phase 3: Rewiring the Process (Small PRs)

Small pull requests are the backbone of TBD. A large PR is a cognitive nightmare that leads to shallow reviews and delayed deployments.

5. Enforce Hard PR Size Limits

Don’t make small PRs a suggestion; make them a constraint.

• The Rule: Set a soft limit of ~300 lines and a hard limit of ~400–500 lines per PR.
• The Logic: Constraints force better behavior. If a task is too big, it forces the developer to think about how to slice it vertically.

6. Vertical vs. Horizontal Slicing

Stop splitting work by “Backend PR,” “Database PR,” and “Frontend PR”. This creates artificial dependencies and forces you to wait until all are done before merging.

• The Strategy: Slice vertically. One PR should deliver a minimal end-to-end functionality (even if hidden by a flag), followed by another PR that extends that behavior.

Phase 4: The Cultural Shift (The Hard Part)

Trunk-based development is 10% tooling and 90% discipline.

7. Optimize for Review Speed, Not Just Quality

If reviews take days, developers will batch work to avoid the “waiting tax”.

• Expectation: A PR should be reviewed within a few hours, not days.
• Technique: If a PR is small (under 300 – 400 lines), it takes 15 minutes to review. If it’s still stuck, do live reviews or pair programming to clear the logjam.

8. Accept “Ugly but Correct”

Flow matters more than perfection.

• The Mindset: It is better to merge a small, slightly imperfect (but safe) change today than a “perfect” massive change next week. You can refactor and improve incrementally once the code is integrated -> but don’t forget to refactor.

Phase 5: The Cleanup and AI Reality

AI-assisted coding is generating more code than ever. If you don’t have small changes and fast integration, your workflow will collapse under the sheer volume of AI-generated changes.

9. The Non-Optional Cleanup

Feature flags and abstractions are great, but they create technical debt if left forever.

• The Rule: Once a rollout is 100% successful, deleting the old code and the flag is part of the original task, not a “nice-to-have” for later.

10. Track Your Behavior (Metrics)

Stop guessing if you are doing TBD. Measure it.

• KPIs: Track average PR size, PR lifetime, and merges per developer per day.
• Reality Check: If your PRs live for days and contain thousands of lines, you are still doing feature-branch development.

Common Failure Mode

Teams adopt feature flags but still keep long-lived branches.
That is not trunk-based development.
The branch lifetime matters more than the branching strategy itself.

Final Thought

Trunk-based development feels uncomfortable at first because it goes against the natural desire to be “complete” and “polished” before sharing work. It requires you to prioritize the system’s flow over your individual comfort.

If you fix just one thing this month, make your pull requests radically smaller. Faster reviews, fewer bugs, and smoother delivery will follow. Everything else is just details.

The post Trunk-Based Development: From Chaos to Flow appeared first on CodeCraft Diary.

You’ve got 85% code coverage. Your CI pipeline is green. You ship to production — and things break in ways your tests never caught. Sound familiar?

I’ve been there. And for a long time, I thought the answer was more tests. What I actually needed was better tests. That’s exactly what mutation testing taught me, and after using Infection PHP in production projects through 2025 and into 2026, I can confidently say it changed how I think about test quality entirely.

Previous article in this category: https://codecraftdiary.com/2026/04/18/laravel-testing-mistakes/

The Dirty Secret of Code Coverage

Code coverage tells you which lines were executed during your test run. It says nothing about whether your assertions are actually meaningful.

Consider this classic trap:

<?php

class OrderDiscountCalculator
{
    public function calculate(float $price, int $quantity): float
    {
        if ($quantity >= 10) {
            return $price * 0.9;
        }

        return $price;
    }
}

<?php

class OrderDiscountCalculator
{
    public function calculate(float $price, int $quantity): float
    {
        if ($quantity >= 10) {
            return $price * 0.9;
        }

        return $price;
    }
}

And a test that covers it 100%:

<?php

use PHPUnit\Framework\TestCase;

class OrderDiscountCalculatorTest extends TestCase
{
    public function testCalculate(): void
    {
        $calculator = new OrderDiscountCalculator();

        // Both branches hit — 100% coverage!
        $calculator->calculate(100.0, 15);
        $calculator->calculate(100.0, 5);
    }
}

<?php

use PHPUnit\Framework\TestCase;

class OrderDiscountCalculatorTest extends TestCase
{
    public function testCalculate(): void
    {
        $calculator = new OrderDiscountCalculator();

        // Both branches hit — 100% coverage!
        $calculator->calculate(100.0, 15);
        $calculator->calculate(100.0, 5);
    }
}

This test covers 100% of the code. It also asserts absolutely nothing. If someone changes 0.9 to 0.5, your test suite stays green while your customers get 50% off everything. That’s a very expensive bug.

This is precisely the problem mutation testing solves.

What Is Mutation Testing?

Mutation testing works by automatically introducing small bugs — called mutants — into your source code, then running your test suite against each mutated version. If your tests catch the bug (the mutant is killed), great. If your tests still pass with the bug in place (the mutant survives), you have a gap.

Common mutations include things like:

• Changing >= to > or <=
• Replacing + with -
• Flipping true to false
• Removing entire return statements

The metric you care about is the Mutation Score Indicator (MSI) — the percentage of mutants your tests kill. A high MSI means your tests are genuinely sensitive to regressions.

Getting Started with Infection PHP

Infection is the de facto mutation testing framework for PHP. It integrates cleanly with PHPUnit and runs as a Composer dev dependency.

composer require --dev infection/infection

composer require --dev infection/infection

Run it for the first time with:

./vendor/bin/infection --threads=4

./vendor/bin/infection --threads=4

Infection will run your existing test suite, then start generating and testing mutants. On a modern project with --threads=4, it’s fast enough to include in a CI pipeline.

A Real-World Example: Catching What Coverage Misses

Let me walk you through a scenario I actually encountered on a SaaS project — a pricing engine with tiered discounts.

<?php

class TieredPricingService
{
    private const TIERS = [
        100 => 0.70, // 30% discount for 100+
        50  => 0.80, // 20% discount for 50+
        10  => 0.90, // 10% discount for 10+
    ];

    public function getPrice(float $unitPrice, int $quantity): float
    {
        foreach (self::TIERS as $minQuantity => $multiplier) {
            if ($quantity >= $minQuantity) {
                return round($unitPrice * $multiplier * $quantity, 2);
            }
        }

        return round($unitPrice * $quantity, 2);
    }
}

<?php

class TieredPricingService
{
    private const TIERS = [
        100 => 0.70, // 30% discount for 100+
        50  => 0.80, // 20% discount for 50+
        10  => 0.90, // 10% discount for 10+
    ];

    public function getPrice(float $unitPrice, int $quantity): float
    {
        foreach (self::TIERS as $minQuantity => $multiplier) {
            if ($quantity >= $minQuantity) {
                return round($unitPrice * $multiplier * $quantity, 2);
            }
        }

        return round($unitPrice * $quantity, 2);
    }
}

My original tests covered all branches. PHPUnit reported 100% coverage. But when I ran Infection, it flagged a surviving mutant — it changed >= to > in the tier check, and my test for exactly 10 units didn’t catch it because I only tested with 11. The boundary condition was untested.

Here’s what the corrected test looked like after Infection exposed the gap:

<?php

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\DataProvider;

class TieredPricingServiceTest extends TestCase
{
    private TieredPricingService $service;

    protected function setUp(): void
    {
        $this->service = new TieredPricingService();
    }

    #[DataProvider('pricingProvider')]
    public function testGetPrice(float $unitPrice, int $quantity, float $expected): void
    {
        $this->assertSame($expected, $this->service->getPrice($unitPrice, $quantity));
    }

    public static function pricingProvider(): array
    {
        return [
            'below first tier'         => [10.0, 5,   50.00],
            'exactly at 10 tier'       => [10.0, 10,  90.00],  // boundary — was missing!
            'above 10 tier'            => [10.0, 11,  99.00],
            'exactly at 50 tier'       => [10.0, 50,  400.00], // boundary
            'exactly at 100 tier'      => [10.0, 100, 700.00], // boundary
            'above highest tier'       => [10.0, 200, 1400.00],
        ];
    }
}

<?php

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\DataProvider;

class TieredPricingServiceTest extends TestCase
{
    private TieredPricingService $service;

    protected function setUp(): void
    {
        $this->service = new TieredPricingService();
    }

    #[DataProvider('pricingProvider')]
    public function testGetPrice(float $unitPrice, int $quantity, float $expected): void
    {
        $this->assertSame($expected, $this->service->getPrice($unitPrice, $quantity));
    }

    public static function pricingProvider(): array
    {
        return [
            'below first tier'         => [10.0, 5,   50.00],
            'exactly at 10 tier'       => [10.0, 10,  90.00],  // boundary — was missing!
            'above 10 tier'            => [10.0, 11,  99.00],
            'exactly at 50 tier'       => [10.0, 50,  400.00], // boundary
            'exactly at 100 tier'      => [10.0, 100, 700.00], // boundary
            'above highest tier'       => [10.0, 200, 1400.00],
        ];
    }
}

After adding boundary assertions, Infection’s MSI jumped from 61% to 94%. That’s the difference between a test suite that gives you false confidence and one that actually has your back.

Configuring Infection for Your Project

Infection is configured via infection.json5 in your project root. Here’s a production-ready config I use:

{
    "$schema": "vendor/infection/infection/resources/schema.json",
    "source": {
        "directories": ["src"],
        "excludes": ["src/Infrastructure/Migrations"]
    },
    "mutators": {
        "@default": true
    },
    "testFramework": "phpunit",
    "testFrameworkOptions": "--testsuite=unit",
    "minMsi": 85,
    "minCoveredMsi": 90,
    "threads": 4,
    "logs": {
        "text": "var/log/infection.log",
        "html": "var/log/infection.html",
        "summary": "var/log/infection-summary.log"
    }
}

{
    "$schema": "vendor/infection/infection/resources/schema.json",
    "source": {
        "directories": ["src"],
        "excludes": ["src/Infrastructure/Migrations"]
    },
    "mutators": {
        "@default": true
    },
    "testFramework": "phpunit",
    "testFrameworkOptions": "--testsuite=unit",
    "minMsi": 85,
    "minCoveredMsi": 90,
    "threads": 4,
    "logs": {
        "text": "var/log/infection.log",
        "html": "var/log/infection.html",
        "summary": "var/log/infection-summary.log"
    }
}

The minMsi and minCoveredMsi thresholds are important — they let your CI pipeline fail if mutation score drops below acceptable levels, the same way PHPUnit can fail below a coverage threshold.

Integrating Into CI (GitHub Actions)

Here’s a GitHub Actions job I’ve been running since mid-2025:

mutation-testing:
  runs-on: ubuntu-latest
  needs: tests
  steps:
    - uses: actions/checkout@v4

    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        coverage: xdebug

    - name: Install dependencies
      run: composer install --no-interaction

    - name: Run Infection
      run: ./vendor/bin/infection --threads=4 --min-msi=85 --min-covered-msi=90

mutation-testing:
  runs-on: ubuntu-latest
  needs: tests
  steps:
    - uses: actions/checkout@v4

    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        coverage: xdebug

    - name: Install dependencies
      run: composer install --no-interaction

    - name: Run Infection
      run: ./vendor/bin/infection --threads=4 --min-msi=85 --min-covered-msi=90

One important note: Infection requires a coverage driver (Xdebug or PCOV) to know which mutants are relevant to which tests. PCOV is faster for large codebases; Xdebug gives more detail. I use Xdebug locally and PCOV in CI.

Common Objections — And Honest Answers

“It’s too slow.” It can be on large codebases, but --threads and configuring source.excludes to skip generated code, migrations, and DTOs makes a huge difference. I typically exclude everything that has no business logic.

“The MSI is too low to be useful.” Start with --min-msi=0 and just look at the HTML report. Prioritize killing mutants in your core domain logic first — that’s where bugs actually hurt.

“It produces too many surviving mutants.” Some mutants are genuinely equivalent (they don’t change behavior). Infection lets you mark these as ignored in config. Over time your noise floor drops significantly.

What My Workflow Looks Like in 2026

My current approach on active PHP projects:

1. PHPUnit with strict coverage for the fast feedback loop during development.
2. Infection on every PR targeting only changed files — using --git-diff-filter (available since Infection 0.27) to keep CI times reasonable.
3. Full Infection run weekly on the main branch to catch gradual MSI drift.

The --git-diff-filter flag is a game-changer for larger repos — it only mutates code touched in the current diff, so mutation testing stays practical even on monorepos.

./vendor/bin/infection --git-diff-filter=AM --threads=8

./vendor/bin/infection --git-diff-filter=AM --threads=8

Final Thoughts

Code coverage is a floor, not a ceiling. It tells you the minimum — which lines were touched. Mutation testing tells you something far more valuable: whether those lines are protected by tests that would actually catch a regression.

If you’re publishing technical content in 2026 and you’re not talking about mutation testing, you’re leaving one of PHP’s most powerful quality tools completely off the table. The tooling has matured, the CI integration is straightforward, and the payoff in confidence is real.

Start with a single service class. Run Infection. Look at what survives. I promise you’ll find something surprising.

Resources:

• Infection PHP documentation
• Infection GitHub repository
• PHPUnit documentation

The post How Mutation Testing Exposes the Truth (PHP 2026 Edition) appeared first on CodeCraft Diary.

If you’ve been following my series on Refactoring & Patterns, you know I’m a fan of the Introduce Parameter Object pattern. But today, I want to go deeper and talk about one of the smallest, yet most powerful building blocks of clean architecture: Value Objects.

Previous article in this category: https://codecraftdiary.com/2026/04/11/fat-controller-laravel-refactor/

The “Price” of Primitive Obsession

Imagine you’re working on an e-commerce platform. You have a Product and a Discount.

public function applyDiscount(float $price, float $discountPercentage):float
{
    if ($discountPercentage < 0 || $discountPercentage > 100) {
        throw new InvalidArgumentException("Invalid discount");
    }

    return $price - ($price * ($discountPercentage / 100));
}

public function applyDiscount(float $price, float $discountPercentage):float
{
    if ($discountPercentage < 0 || $discountPercentage > 100) {
        throw new InvalidArgumentException("Invalid discount");
    }

    return $price - ($price * ($discountPercentage / 100));
}

At first glance, this looks fine. But in a real-world application, that $price is floating around (pun intended) everywhere.

• Is it USD or EUR?
• Does it include VAT?
• What about rounding?

And more importantly: what happens if you accidentally pass $discountPercentage as $price?

PHP won’t complain. Both are floats. You just sold a MacBook for $15.

On top of that, floats introduce precision issues, which makes them a poor choice for financial calculations in the first place.

What Exactly is a Value Object?

A Value Object (VO) is an object that is defined by its value rather than its identity.

Two Value Objects with the same data are considered equal—even if they are different instances.

In modern PHP (8.2+), a well-designed Value Object has three key characteristics:

• Immutability – once created, it cannot change
• Validation – it cannot exist in an invalid state
• Self-documentation – the type clearly expresses intent

A Better Approach: Explicit Domain Types

Let’s refactor the previous example.

final readonly class Price
{
    public function __construct(
        public int $amount, // in cents
        public Currency $currency
    ) {
        if ($this->amount < 0) {
            throw new InvalidPriceException("Price cannot be negative.");
        }
    }

    public function add(Price $other): Price
    {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatchException();
        }

        return new Price($this->amount + $other->amount, $this->currency);
    }

    public function equals(Price $other): bool
    {
        return $this->amount === $other->amount
            && $this->currency === $other->currency;
    }
}

final readonly class Price
{
    public function __construct(
        public int $amount, // in cents
        public Currency $currency
    ) {
        if ($this->amount < 0) {
            throw new InvalidPriceException("Price cannot be negative.");
        }
    }

    public function add(Price $other): Price
    {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatchException();
        }

        return new Price($this->amount + $other->amount, $this->currency);
    }

    public function equals(Price $other): bool
    {
        return $this->amount === $other->amount
            && $this->currency === $other->currency;
    }
}

A few important things are happening here:

• Encapsulation – price logic lives inside the Price class
• Type safety – you cannot mix currencies accidentally
• Immutability – every operation returns a new instance
• Precision – using integers avoids float rounding issues

Why This Matters (Especially Today)

With AI-assisted development becoming standard, types matter more than ever.

When you use primitives, tools like GitHub Copilot or ChatGPT have to guess intent.

When you use a Price or EmailAddress object, both humans and AI can:

• understand constraints immediately
• discover available behavior via methods
• avoid invalid states by design

You’re not just writing code—you’re defining a clear contract.

Real-World Refactoring: Email

How often have you written this?

if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {<br>    throw new Exception("Invalid email");<br>}

if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {<br>    throw new Exception("Invalid email");<br>}

If it appears in multiple places, that’s duplication—and a maintenance risk.

Let’s move that logic into a Value Object:

final readonly class EmailAddress
{
    private string $value;

    public function __construct(string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException($value);
        }

        $this->value = strtolower(trim($value));
    }

    public function getDomain(): string
    {
        return substr(strrchr($this->value, "@"), 1);
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

final readonly class EmailAddress
{
    private string $value;

    public function __construct(string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException($value);
        }

        $this->value = strtolower(trim($value));
    }

    public function getDomain(): string
    {
        return substr(strrchr($this->value, "@"), 1);
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

Now your service layer becomes much cleaner:

// BEFORE
public function registerUser(string $email, string $password) { ... }

// AFTER
public function registerUser(EmailAddress $email, Password $password) { ... }

// BEFORE
public function registerUser(string $email, string $password) { ... }

// AFTER
public function registerUser(EmailAddress $email, Password $password) { ... }

The moment execution reaches registerUser, you already know the email is valid.

Validation is handled at the boundary of your system—not scattered across your codebase.

Logic-Heavy Value Objects

A common mistake is treating Value Objects as simple data containers.

In practice, they should encapsulate behavior related to that data.

Instead of passing:

string $startDate, string $endDate

string $startDate, string $endDate

You can model:

OrderDateRange

OrderDateRange

With methods like:

• overlapsWith()
• isWithinLastMonth()
• getDurationInDays()

This reduces cognitive load in your services and keeps domain logic where it belongs.

When NOT to Use Value Objects

Not everything needs to be a Value Object.

Ask yourself:

• Does this data have validation rules?
• Is it reused in multiple places?
• Does it represent a domain concept (SKU, IBAN, Email, Price)?

If the answer is yes, a Value Object is likely justified.

If you’re building a quick prototype, primitives are fine. Just be aware of the trade-offs.

Performance Considerations

A common concern used to be performance—creating many small objects instead of using primitives.

In modern PHP, object instantiation is highly optimized. The overhead is negligible compared to the cost of bugs caused by invalid states.

More importantly:

• immutable objects are predictable
• they eliminate side effects
• they are naturally safe in concurrent or async contexts

Summary

Refactoring toward Value Objects is one of the most effective ways to improve code quality.

It forces you to think in terms of domain concepts, not just data types.

Practical steps:

• Look at a complex service class
• Find a variable validated in multiple places
• Extract it into a readonly Value Object
• Move related logic into that object

You’ll end up with code that is easier to read, safer to modify, and harder to break.

The post Mastering Value Objects in PHP 8.5+ (2026 Edition) appeared first on CodeCraft Diary.

It’s pull requests.

If you read about trunk-based development, you’ll see the same advice repeated everywhere: small changes, frequent merges, fast feedback. Sounds simple. Almost obvious.

And yet — in reality — most teams are nowhere near that.

I’ve personally seen pull requests sitting open for months. Not days. Not weeks. Months.

At one point, we had a pull request in our team that was open for more than six months.

Six.

Months.

At that point, it’s no longer a pull request. It’s a parallel universe.

Below this link you can read first article about Trunk-Based Development https://codecraftdiary.com/2026/04/04/trunk-based-development-why-most-teams-think-they-use-it-but-dont/

The Hidden Cost of Large Pull Requests

Let’s be precise about what’s happening here.

A large pull request is not just “a bit harder to review”. It fundamentally breaks your delivery system.

Here’s what actually happens:

1. Review becomes a cognitive nightmare

When a PR has:

• 1,000+ lines
• multiple concerns (API, DB, UI, validation)
• partial refactors

No one can realistically review it properly.

So what happens?

• reviewers skim
• they miss edge cases
• they delay the review (“I’ll look at it later”)

And “later” turns into never.

2. Feedback loop collapses

Fast feedback is the core of modern development.

But with large PRs:

• feedback comes late
• feedback is vague
• feedback is expensive to apply

Instead of:

“Fix this small thing”

You get:

“This entire approach might be wrong”

Now the author has to:

• rethink everything
• rework large chunks of code
• re-request review

Cycle time explodes.

3. Merge becomes risky

The bigger the PR, the higher the risk:

• conflicts with main branch
• outdated assumptions
• broken integrations

So teams hesitate.

And hesitation kills flow.

4. Work gets batched (and everything slows down)

This is the core anti-pattern.

Instead of shipping continuously, developers start batching work:

“I’ll just add one more thing before I open the PR”

Then:

“Actually, I’ll include this refactor too”

And suddenly:

• PR grows
• review slows
• merge is delayed

It’s a vicious cycle.

The Real Reason Your PRs Are Too Big

Let’s be honest — this is not a tooling issue.

It’s behavioral.

Here are the real causes:

1. “I want it to be complete”

This is the most common mindset:

“I’ll open the PR when the feature is done.”

Sounds reasonable. It’s also completely wrong.

Because “done” often means:

• multiple layers
• edge cases
• polish

Which leads to massive PRs.

2. Fear of breaking things

Without proper safety mechanisms (tests, feature flags), developers avoid small merges.

So they wait.

And wait.

And accumulate changes.

3. Poor slicing of work

Most developers split work like this:

• backend PR
• frontend PR
• DB migration PR

Instead of:

• vertical slices that deliver value end-to-end

This creates artificial dependencies and forces larger PRs.

4. Review culture is asynchronous and slow

If reviews take:

• hours
• or days

Developers adapt by batching work.

Why open a small PR if it will just sit there?

The 6-Month Pull Request Problem

Let’s go back to that real example.

A PR open for six months.

What does that actually mean?

• The branch is completely outdated
• The context is lost
• The author doesn’t remember all decisions
• The reviewers don’t understand it anymore

At that point, you have only two realistic options:

1. Merge it blindly (high risk)
2. Close it and start over (lost work)

Both are bad.

But the real failure happened much earlier — when the PR was allowed to grow beyond control.

How to Fix This (Practically)

This is not about theory. These are concrete practices that work.

1. Enforce a hard PR size limit

Set a rule:

• Max ~300–400 lines per PR

Not as a suggestion.

As a constraint.

Why?

Because constraints force better behavior:

• better slicing
• fewer concerns per change
• faster reviews

2. Merge incomplete work (safely)

This is the shift most teams struggle with.

You don’t need “finished features” to merge.

You need:

• safe code
• controlled exposure

Use:

• feature flags
• toggles
• hidden UI states

This allows you to:

• merge early
• iterate safely

3. Slice vertically, not horizontally

Instead of:

• PR 1: database
• PR 2: API
• PR 3: UI

Do:

• PR 1: minimal end-to-end functionality
• PR 2: extend behavior
• PR 3: polish

Each PR:

• delivers something usable
• is independently testable
• is small

4. Optimize review speed (not just quality)

Set expectations:

• PR should be reviewed within a few hours
• not days

Ways to achieve this:

• smaller PRs (obviously)
• clear ownership
• synchronous reviews when needed (pairing)

5. Accept “ugly but correct” code (temporarily)

This is uncomfortable but critical.

Sometimes the right move is:

“Merge this small, slightly imperfect change now”

Instead of:

“Wait until it’s perfectly clean”

Why?

Because flow matters more than perfection.

You can always:

• refactor later (but don’t forget — it’s important for code cleanup)
• improve incrementally

6. Track your actual behavior

If you want to be serious about this, measure:

• average PR size
• PR lifetime
• number of merges per day

Reality check:

If your PRs:

• live for days
• contain hundreds/thousands of lines

You are not doing trunk-based development.

No matter what your team says.

What About Large Architectural Changes?

A common question that comes up here is: does this apply when you’re doing a complete architectural overhaul of a service?

The short answer is yes — and there’s a specific pattern for it called Branch by Abstraction.

Instead of keeping the new architecture in a separate Git branch for months (and facing a merge nightmare later), you keep both versions in the main branch simultaneously. It feels messy at first. It’s much safer in practice.

Here’s how it works in combination with feature flags:

• You merge small, incremental pieces of the new architecture daily — never a big bang.
• You run dark launches: the new code executes in production, but its results are ignored or compared against the old implementation. No user impact, real-world validation.
• When confidence is high enough, you flip the flag and the new architecture goes live instantly.

The two things that make this work:

1. The flag has to exist from the start. Not added later as an afterthought. If you begin the migration without a flag, you’ll end up in the same situation as a long-lived branch — just in the main branch instead.

2. The cleanup phase is not optional. Once the rollout is 100% successful, deleting the old code and removing the flag is not a nice-to-have. It’s part of the work. Skipping this step is how codebases become impossible to understand.

The tradeoff is real: having two architectures in the codebase simultaneously requires more discipline and coordination from the team.

Trunk-Based Development pt. 3: https://codecraftdiary.com/2026/05/18/trunk-based-development-roadmap/

The Real Mindset Shift

This is the uncomfortable truth:

Small pull requests are not a technical practice.
They are a discipline.

They require you to:

• let go of “completeness”
• embrace incremental delivery
• prioritize flow over polish

And that’s hard.

Because it goes against how most developers naturally think about work.

Final Thought

That 6-month pull request wasn’t an exception.

It was just an extreme version of a very common problem.

Most teams are operating with:

• oversized changes
• slow feedback
• delayed merges

And then they wonder why delivery feels slow.

If you fix just one thing, fix this:

Make your pull requests smaller. Radically smaller.

Everything else — faster reviews, fewer bugs, smoother delivery — follows from that.

Not the other way around.

The post Trunk-Based Development: Your Pull Requests Are Still Too Big appeared first on CodeCraft Diary.

If your tests don’t catch real bugs, they’re not just useless—they give you a false sense of confidence.

In this article, we’ll go through the most common Laravel testing mistakes that quietly break the value of your test suite, along with practical examples and better approaches.

You can be also interested in testing database logic https://codecraftdiary.com/2026/01/03/testing-database-logic-what-to-test-what-to-skip-and-why-it-matters/

1. Testing Implementation Instead of Behavior

One of the biggest mistakes is writing tests that mirror your code instead of validating what your application actually does.

Bad example

public function test_it_calls_service_method()
{
    $service = Mockery::mock(UserService::class);
    $service->shouldReceive('createUser')->once();

    $controller = new UserController($service);
    $controller->store(new Request([...]));
}

public function test_it_calls_service_method()
{
    $service = Mockery::mock(UserService::class);
    $service->shouldReceive('createUser')->once();

    $controller = new UserController($service);
    $controller->store(new Request([...]));
}

This test only checks that a method was called. It doesn’t verify:

• what was created
• whether the data is correct
• whether anything actually works

Better approach

public function test_user_is_created()
{
    $response = $this->post('/users', [
        'name' => 'John Doe',
        'email' => 'john@example.com',
    ]);

    $response->assertStatus(201);

    $this->assertDatabaseHas('users', [
        'email' => 'john@example.com',
    ]);
}

public function test_user_is_created()
{
    $response = $this->post('/users', [
        'name' => 'John Doe',
        'email' => 'john@example.com',
    ]);

    $response->assertStatus(201);

    $this->assertDatabaseHas('users', [
        'email' => 'john@example.com',
    ]);
}

Focus on observable behavior, not internal calls.

2. Overusing Mocks

Mocks are powerful—but overusing them leads to fragile and meaningless tests.

Problem

When everything is mocked:

• you’re not testing real integration
• your tests pass even if the system is broken

Http::fake();

$response = $this->get('/weather');

$response->assertStatus(200);

Http::fake();

$response = $this->get('/weather');

$response->assertStatus(200);

This tells you nothing about:

• response structure
• data correctness
• edge cases

Better approach

Mock only what you must (external services), and assert meaningful output:

Http::fake([
    '*' => Http::response(['temp' => 25], 200),
]);

$response = $this->get('/weather');

$response->assertJson([
    'temperature' => 25,
]);

Http::fake([
    '*' => Http::response(['temp' => 25], 200),
]);

$response = $this->get('/weather');

$response->assertJson([
    'temperature' => 25,
]);

Rule of thumb:
Mock boundaries, not your own logic.

3. Writing Tests That Always Pass

Some tests are written in a way that they can’t fail—even if the code is broken.

Example

public function test_response_is_ok()
{
    $response = $this->get('/users');

    $response->assertStatus(200);
}

public function test_response_is_ok()
{
    $response = $this->get('/users');

    $response->assertStatus(200);
}

This test will pass even if:

• the response is empty
• the wrong data is returned
• business logic is broken

Better approach

$response->assertJsonStructure([
    'data' => [
        '*' => ['id', 'name', 'email']
    ]
]);

$response->assertJsonStructure([
    'data' => [
        '*' => ['id', 'name', 'email']
    ]
]);

Or even better:

$this->assertDatabaseCount('users', 3);

$this->assertDatabaseCount('users', 3);

Ask yourself:
“What bug would this test catch?”
If the answer is “none”, rewrite it.

4. Ignoring Edge Cases

Most bugs don’t happen in the “happy path”. They happen at the edges.

Common mistake

Only testing valid input:

$this->post('/users', [
    'email' => 'john@example.com',
]);

$this->post('/users', [
    'email' => 'john@example.com',
]);

Better approach

Test invalid scenarios:

$this->post('/users', [
    'email' => 'not-an-email',
])->assertSessionHasErrors('email');

$this->post('/users', [
    'email' => 'not-an-email',
])->assertSessionHasErrors('email');

Also test:

• missing fields
• duplicate values
• unexpected input

Good tests try to break your application.

5. Testing Too Much in Unit Tests

Unit tests should be fast and focused. But many developers turn them into mini integration tests.

Example

public function test_order_creation()
{
    $order = OrderService::create([...]);

    $this->assertDatabaseHas('orders', [...]);
}

public function test_order_creation()
{
    $order = OrderService::create([...]);

    $this->assertDatabaseHas('orders', [...]);
}

This mixes:

• business logic
• database layer

Better approach

Split responsibilities:

Unit test (logic only):

public function test_total_price_is_calculated_correctly()
{
    $total = OrderCalculator::calculate([100, 200]);

    $this->assertEquals(300, $total);
}

public function test_total_price_is_calculated_correctly()
{
    $total = OrderCalculator::calculate([100, 200]);

    $this->assertEquals(300, $total);
}

Feature test (full flow):

$this->post('/orders', [...]);

$this->assertDatabaseHas('orders', [...]);

$this->post('/orders', [...]);

$this->assertDatabaseHas('orders', [...]);

Keep your test layers clean.

6. Not Using Factories Properly

Laravel factories are powerful, but many developers misuse them.

Problem

Hardcoding everything:

User::create([
    'name' => 'Test',
    'email' => 'test@example.com',
]);

User::create([
    'name' => 'Test',
    'email' => 'test@example.com',
]);

Better approach

$user = User::factory()->create();

$user = User::factory()->create();

Even better:

$user = User::factory()->state([
    'email_verified_at' => now(),
])->create();

$user = User::factory()->state([
    'email_verified_at' => now(),
])->create();

Benefits:

• less boilerplate
• more flexible tests
• easier maintenance

7. Not Cleaning Up Test Data

Dirty test data can cause flaky tests.

Problem

Tests depend on previous state.

Solution

Use:

use Illuminate\Foundation\Testing\RefreshDatabase;

use Illuminate\Foundation\Testing\RefreshDatabase;

This ensures:

• clean DB for each test
• consistent results

Flaky tests destroy trust in your test suite.

8. Writing Tests That Are Too Complex

If your test is hard to read, it’s probably doing too much.

Example

public function test_everything()
{
    // 50 lines of setup
    // 10 assertions
}

public function test_everything()
{
    // 50 lines of setup
    // 10 assertions
}

Better approach

Break it down:

public function test_user_can_register() {}
public function test_email_must_be_unique() {}
public function test_password_is_required() {}

public function test_user_can_register() {}
public function test_email_must_be_unique() {}
public function test_password_is_required() {}

Each test should answer one question.

9. Ignoring Performance

Slow tests are often skipped—and skipped tests are useless tests.

Problem

• too many DB calls
• unnecessary setup
• heavy fixtures

Tips

• use in-memory database (SQLite)
• avoid unnecessary seeding
• keep unit tests fast

Fast tests = tests you actually run.

10. Not Testing Real User Flows

Testing isolated pieces is not enough.

Problem

You test services and controllers separately, but never the full flow.

Example

public function test_user_can_register_and_login()
{
    $this->post('/register', [
        'email' => 'john@example.com',
        'password' => 'password',
    ]);

    $this->post('/login', [
        'email' => 'john@example.com',
        'password' => 'password',
    ])->assertRedirect('/dashboard');
}

public function test_user_can_register_and_login()
{
    $this->post('/register', [
        'email' => 'john@example.com',
        'password' => 'password',
    ]);

    $this->post('/login', [
        'email' => 'john@example.com',
        'password' => 'password',
    ])->assertRedirect('/dashboard');
}

This is what actually matters:
Can the user complete the action?

Final Thoughts

Laravel makes testing easy—but writing useful tests is a different skill.

If your tests:

• only check status codes
• mock everything
• mirror your implementation

…then they’re not protecting your application.

Instead, focus on:

• real behavior
• meaningful assertions
• edge cases
• realistic user flows

A smaller set of high-quality tests is far more valuable than a large suite of weak ones.

Quick Checklist

Before committing a test, ask:

• Does this test fail if something important breaks?
• Am I testing behavior, not implementation?
• Would this catch a real bug?
• Is this test simple and readable?

If the answer is “no”, it’s time to improve it.

Well-written tests are not just about coverage—they’re about confidence. And confidence comes from tests that actually matter.

The post Laravel Testing Mistakes That Make Your Tests Useless appeared first on CodeCraft Diary.

A controller starts small. Clean. Readable.

Then features get added.

Deadlines hit.

Logic piles up.

And suddenly, you’re staring at a 500-line controller that handles validation, business logic, database writes, API calls, and maybe even a bit of formatting “just for now.”

This is what we call a Fat Controller — and it’s one of the most common maintainability problems in Laravel applications.

In this article, we’ll take a real-world approach and refactor a fat controller into a cleaner, scalable structure using principles inspired by Clean Architecture.

No theory overload. Just practical steps.

Previous Article in this category : https://codecraftdiary.com/2026/03/21/ai-driven-refactoring/

The Problem: A Real Fat Controller Example

Let’s start with something painfully familiar:

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // Validation
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        // Business logic
        $total = 0;

        foreach ($validated['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

            $total += $product->price * $item['quantity'];

            $product->stock -= $item['quantity'];
            $product->save();
        }

        // Save order
        $order = Order::create([
            'user_id' => $validated['user_id'],
            'total' => $total,
        ]);

        // Save items
        foreach ($validated['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        // External API call
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

        return response()->json($order);
    }
}

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // Validation
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        // Business logic
        $total = 0;

        foreach ($validated['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

            $total += $product->price * $item['quantity'];

            $product->stock -= $item['quantity'];
            $product->save();
        }

        // Save order
        $order = Order::create([
            'user_id' => $validated['user_id'],
            'total' => $total,
        ]);

        // Save items
        foreach ($validated['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        // External API call
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

        return response()->json($order);
    }
}

What’s wrong here?

• Controller handles too many responsibilities
• Business logic is not reusable
• Hard to test
• Tight coupling to Eloquent and external APIs
• Changes are risky

Goal: What “Clean” Looks Like

We want to move toward:

• Thin controllers
• Isolated business logic
• Testable services
• Clear boundaries between layers

We’re not going full academic Clean Architecture. We’re applying just enough structure to stay sane.

Step 1: Extract Business Logic into a Service

First, move the core logic out of the controller.

class CreateOrderService
{
    public function handle(array $data): Order
    {
        $total = 0;

        foreach ($data['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

            $total += $product->price * $item['quantity'];

            $product->stock -= $item['quantity'];
            $product->save();
        }

        $order = Order::create([
            'user_id' => $data['user_id'],
            'total' => $total,
        ]);

        foreach ($data['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

        return $order;
    }
}

class CreateOrderService
{
    public function handle(array $data): Order
    {
        $total = 0;

        foreach ($data['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

            $total += $product->price * $item['quantity'];

            $product->stock -= $item['quantity'];
            $product->save();
        }

        $order = Order::create([
            'user_id' => $data['user_id'],
            'total' => $total,
        ]);

        foreach ($data['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

        return $order;
    }
}

Controller becomes:

class OrderController extends Controller
{
    public function store(Request $request, CreateOrderService $service)
    {
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        $order = $service->handle($validated);

        return response()->json($order);
    }
}

class OrderController extends Controller
{
    public function store(Request $request, CreateOrderService $service)
    {
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        $order = $service->handle($validated);

        return response()->json($order);
    }
}

Improvement:

• Controller is now thin
• Logic is reusable
• Easier to test

But we’re not done yet.

Step 2: Introduce a Data Transfer Object (DTO)

Passing raw arrays is fragile.

Let’s fix that.

class CreateOrderData
{
    public function __construct(
        public int $userId,
        public array $items
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            $data['user_id'],
            $data['items']
        );
    }
}

class CreateOrderData
{
    public function __construct(
        public int $userId,
        public array $items
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            $data['user_id'],
            $data['items']
        );
    }
}

Update controller:

$data = CreateOrderData::fromArray($validated);
$order = $service->handle($data);

$data = CreateOrderData::fromArray($validated);
$order = $service->handle($data);

Update service:

public function handle(CreateOrderData $data): Order

public function handle(CreateOrderData $data): Order

Improvement:

• Stronger typing
• Safer refactoring
• Clear contract

Step 3: Decouple External Dependencies

Right now, your service is tightly coupled to:

• Eloquent models
• HTTP client

Let’s extract the webhook logic.

class OrderWebhookService
{
    public function send(Order $order): void
    {
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);
    }
}

class OrderWebhookService
{
    public function send(Order $order): void
    {
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);
    }
}

Inject it:

class CreateOrderService
{
    public function __construct(
        private OrderWebhookService $webhook
    ) {}

    public function handle(CreateOrderData $data): Order
    {
        // logic...

        $this->webhook->send($order);

        return $order;
    }
}

class CreateOrderService
{
    public function __construct(
        private OrderWebhookService $webhook
    ) {}

    public function handle(CreateOrderData $data): Order
    {
        // logic...

        $this->webhook->send($order);

        return $order;
    }
}

Improvement:

• External side effects are isolated
• Easier to mock in tests

Step 4: Make It Testable

Now you can test the service independently:

public function test_it_creates_order()
{
    $service = app(CreateOrderService::class);

    $data = new CreateOrderData(
        userId: 1,
        items: [
            ['id' => 1, 'quantity' => 2],
        ]
    );

    $order = $service->handle($data);

    $this->assertNotNull($order->id);
}

public function test_it_creates_order()
{
    $service = app(CreateOrderService::class);

    $data = new CreateOrderData(
        userId: 1,
        items: [
            ['id' => 1, 'quantity' => 2],
        ]
    );

    $order = $service->handle($data);

    $this->assertNotNull($order->id);
}

Before refactoring, this would require:

• HTTP mocking
• Controller testing
• Complex setup

Now it’s isolated.

Step 5: Optional — Introduce Repositories (Only If Needed)

Don’t overengineer this.

But if your app grows, you might extract:

class ProductRepository
{
    public function find(int $id): ?Product
    {
        return Product::find($id);
    }
}

class ProductRepository
{
    public function find(int $id): ?Product
    {
        return Product::find($id);
    }
}

Then inject it into the service.

When to do this:

• Multiple data sources
• Complex queries
• Domain logic reuse

When NOT to:

• Simple CRUD apps

Before vs After

Common Mistakes to Avoid

1. Moving everything blindly into services

You’ll just create fat services instead of fat controllers.

Keep services focused.

2. Overengineering with too many layers

You don’t need:

• 10 interfaces
• 5 abstractions
• enterprise architecture™

Start simple. Evolve when needed.

3. Ignoring boundaries

Controllers = HTTP
Services = business logic
Models = persistence

Mixing these again = back to chaos.

Key Takeaways

• Fat controllers are a symptom, not the root problem
• The real issue is mixed responsibilities
• Start with service extraction
• Add DTOs for safety
• Isolate side effects (APIs, events)
• Only introduce more abstraction when justified

Final Thought

Clean Architecture in Laravel doesn’t mean rewriting your app into a textbook diagram.

It means one thing:

Making your code easier to change without fear.

And the fastest way to get there?

Start killing your fat controllers — one method at a time.

If this is something you’re dealing with right now, your next step is simple:

Pick your worst controller and extract just one action into a service.

That’s how clean architecture actually starts.

The post Fat Controller Laravel Refactor: Step-by-Step Clean Architecture Guide appeared first on CodeCraft Diary.

No long-lived branches.
Frequent merges.
Small, incremental changes.

Most teams will tell you:

“Yeah, we basically do trunk-based development.”

In practice, they don’t.

What they usually have is a hybrid that keeps the downsides of feature branches — while pretending to get the benefits of trunk-based development.

I’ve seen this pattern in multiple backend teams. On paper, everything looks modern. In reality, delivery is still slow, pull requests are large, and integration is painful.

So let’s break down what’s actually going on.

Last article in this category: https://codecraftdiary.com/2026/03/15/small-pull-requests/

The Illusion of Trunk-Based Development

Ask a team how they work, and you’ll often hear something like:

• “We merge to main frequently”
• “We don’t keep branches for too long”
• “We try to keep PRs small”

Sounds good.

But then you look closer:

• PRs are open for 3–5 days
• branches still contain multiple features
• merges are delayed because reviews are slow
• developers are afraid to merge unfinished work

This is not trunk-based development.

This is just shorter feature branches.

What Real Trunk-Based Development Actually Requires

Trunk-based development is not about branches.

It’s about integration frequency and safety.

At its core, it requires:

• merging to main at least daily (ideally multiple times per day)
• keeping changes small enough to review quickly
• having strong safety mechanisms in place

Without these, trunk-based development collapses.

Where Most Teams Break

1. Pull Requests Are Still Too Big

This is the biggest issue.

A developer starts a “small” feature:

• adds endpoint
• updates service
• modifies database
• adds validation
• fixes something unrelated

Now the PR has:

• 15 files changed
• 600+ lines
• multiple concerns

Review slows down. Feedback increases. Merge is delayed.

At that point, it doesn’t matter what you call your workflow —
you’re not doing trunk-based development.

2. Code Reviews Block Integration

In theory:

“We merge frequently”

In reality:

“We merge when the PR gets approved”

That delay is critical.

If reviews take:

• 1 day → integration is delayed
• 2–3 days → conflicts increase
• 5 days → context is lost

Now developers start stacking changes on top of each other.

And suddenly:

• branches live longer
• PRs get bigger
• merges become risky

3. Teams Are Afraid to Merge Incomplete Work

This is subtle but important.

Developers often think:

“I can’t merge this yet — it’s not finished”

So they keep working on the branch.

The problem:

• the longer the branch lives
• the more it diverges
• the harder it is to merge

Trunk-based development requires a different mindset:

You merge incomplete work safely.

The Missing Piece: Feature Flags

Most teams skip this.

And without it, trunk-based development doesn’t work.

Example

You’re building a new payment flow.

Without feature flags:

• you need to finish everything before merging
• you keep a long-lived branch
• integration is delayed

With feature flags:

if (Feature::enabled('new_payment_flow')) {
    $this->newFlow();
} else {
    $this->oldFlow();
}

if (Feature::enabled('new_payment_flow')) {
    $this->newFlow();
} else {
    $this->oldFlow();
}

Now you can:

• merge partial work
• deploy continuously
• control exposure

Real Example From Practice

I worked with a team that claimed they were doing trunk-based development.

Metrics looked like this:

• average PR size: ~500 lines
• review time: 2–3 days
• merges per developer: ~2 per week

After digging in, the issue was clear:

• developers grouped work “to be efficient”
• reviews were asynchronous and slow
• no feature flags

What changed

We introduced 3 rules:

1. PR must be mergeable within the same day
2. no PR over ~300 lines (soft limit)
3. feature flags for incomplete features

Result after ~3 weeks:

• PR size dropped by ~40%
• review time dropped to hours
• merges increased to multiple per day
• production issues decreased

Not because developers got better.

Because the system changed.

The Hidden Constraint: CI/CD Speed

Here’s something teams often ignore:

You cannot do trunk-based development with slow pipelines.

If your CI takes:

• 20 minutes → friction
• 40 minutes → developers wait
• 60+ minutes → people stop merging frequently

So what happens?

• developers batch changes
• PRs get bigger
• integration slows down

Rule of thumb (2026 reality):

• CI under 10 minutes → good
• under 5 minutes → ideal

Anything above that:
→ you’re actively fighting your workflow

Why This Matters More in 2026

With AI-assisted coding, developers can generate code faster than ever.

That creates a new problem:

volume of changes increases

but review capacity doesn’t

If you don’t enforce:

• small changes
• fast integration
• clear boundaries

your workflow collapses under its own weight.

How to Tell If You’re Actually Doing It

Be honest and check:

• Do you merge to main multiple times per day?
• Are most PRs reviewed within hours, not days?
• Can you safely merge incomplete work?
• Are branches short-lived (hours, not days)?

If not:
→ you’re not doing trunk-based development

Practical Rules You Can Apply Tomorrow

If you want to move closer to real trunk-based development, start here:

1. Limit PR size

Not as a guideline — as a rule.

2. Optimize for review speed

• fewer changes
• clearer intent
• less context switching

3. Introduce feature flags

Without them, you’re stuck.

4. Fix your CI/CD bottlenecks

Speed is not a luxury — it’s a requirement.

5. Stop batching work

Batching feels efficient.
It’s not.

Trunk-Based Development pt. 2: https://codecraftdiary.com/2026/04/29/trunk-based-development-your-pull-requests-are-still-too-big/

Closing Thought

Trunk-based development is not a branching strategy.

It’s a discipline.

Most teams don’t fail because they don’t understand it.
They fail because they don’t change the constraints that make it possible.

If your:

• PRs are big
• reviews are slow
• CI is slow
• merges are risky

then it doesn’t matter what you call your workflow.

You’re still doing feature-branch development — just with better branding.

And that’s exactly why your delivery still feels slower than it should.

The post Trunk-Based Development: Why Most Teams Think They Use It (But Don’t) appeared first on CodeCraft Diary.

Choosing the wrong approach can lead to flaky tests, hidden bugs, and unreliable results.

When writing tests in Laravel, database state can quickly become a source of confusion.

One test passes, another fails. Data seems to “leak” between tests. Records appear when they shouldn’t — or disappear when you expect them to exist.

If you’ve experienced this, you’re not alone.

In most cases, the issue comes down to how your tests handle the database. Laravel provides two primary approaches for this:

• RefreshDatabase
• DatabaseTransactions

At first glance, they seem similar. In reality, they behave very differently — and choosing the wrong one can lead to subtle bugs, flaky tests, or even false confidence in your test suite.

In this guide, you’ll learn exactly how both approaches work, their trade-offs, and when to use each in real-world scenarios.

Last article in this category: https://codecraftdiary.com/2026/03/08/laravel-queue-testing-jobs-retries/

PHP Unit docs: https://phpunit.de/documentation.html

Understanding the Core Problem

Before diving into Laravel specifics, let’s clarify the core issue:

Tests must be isolated.

Each test should run independently, without being affected by previous tests.

If your database is not reset properly between tests:

• data can persist unexpectedly
• test results become unreliable
• debugging becomes painful

Laravel solves this problem using two strategies:

1. Reset the database completely
2. Wrap each test in a transaction and roll it back

Article about practice feature testing in PHP: https://codecraftdiary.com/2025/10/30/feature-testing-in-php-ensuring-the-whole-system-works-together/

Option 1: RefreshDatabase

The RefreshDatabase trait is the most commonly used solution.

use Illuminate\Foundation\Testing\RefreshDatabase;

class UserTest extends TestCase
{
    use RefreshDatabase;
}

use Illuminate\Foundation\Testing\RefreshDatabase;

class UserTest extends TestCase
{
    use RefreshDatabase;
}

How it works

• Runs migrations before tests
• Ensures a clean database state
• Uses transactions internally when possible

What this means in practice

Every test starts with:

• a fresh schema
• no leftover data
• consistent environment

Advantages

1. High reliability

Each test runs in a completely clean environment.

2. Works with everything

• queues
• jobs
• events
• external processes

3. Predictable behavior

No surprises caused by hidden state.

Disadvantages

1. Slower

Running migrations repeatedly can add overhead.

2. Heavier setup

Especially noticeable in large applications.

Option 2: DatabaseTransactions

The DatabaseTransactions trait takes a different approach.

use Illuminate\Foundation\Testing\DatabaseTransactions;

class UserTest extends TestCase
{
    use DatabaseTransactions;
}

use Illuminate\Foundation\Testing\DatabaseTransactions;

class UserTest extends TestCase
{
    use DatabaseTransactions;
}

How it works

• Starts a database transaction before each test
• Rolls it back after the test finishes

What this means

Instead of resetting the database:

• changes are never committed
• everything is undone automatically

Advantages

1. Fast

Transactions are significantly quicker than migrations.

2. Lightweight

No need to rebuild the database schema.

Disadvantages

1. Limited scope

Does NOT work well with:

• queued jobs
• async processes
• separate DB connections

2. Hidden pitfalls

If something runs outside the transaction:

• it won’t be rolled back
• tests may behave inconsistently

Key Differences

Here’s a clear comparison:

When to Use RefreshDatabase

Use RefreshDatabase when:

1. You are testing queues or jobs

Jobs often run outside the main transaction.

dispatch(new ProcessOrderJob($order));

dispatch(new ProcessOrderJob($order));

If you use DatabaseTransactions, the job may not see the data at all.

2. You rely on multiple database connections

Transactions don’t span across connections reliably.

3. You want maximum reliability

If your priority is correctness over speed, this is the safer option.

When to Use DatabaseTransactions

Use DatabaseTransactions when:

1. You are testing simple database interactions

Example:

• repository logic
• basic CRUD operations

2. Performance matters

In large test suites, this can significantly reduce execution time.

3. Everything runs in a single request lifecycle

No queues, no async behavior, no external processes.

Common Mistakes (and How to Avoid Them)

Mixing both traits

use RefreshDatabase, DatabaseTransactions;

use RefreshDatabase, DatabaseTransactions;

This creates unpredictable behavior.

Fix: Choose one strategy per test class.

Using transactions with queues

Queue::fake();

Queue::fake();

Even with fakes, underlying behavior may break if data isn’t committed.

Fix: Use RefreshDatabase for queue-related tests.

Assuming transactions isolate everything

They don’t.

Anything outside the transaction:

• won’t be rolled back
• can pollute your test environment

Ignoring test failures caused by state

Flaky tests often indicate:

improper database isolation

Don’t ignore them — fix the root cause.

Real-World Example

Let’s say you’re testing order processing.

public function test_order_is_processed()
{
    $order = Order::factory()->create();

    dispatch(new ProcessOrderJob($order));

    $this->assertDatabaseHas('orders', [
        'id' => $order->id,
        'status' => 'processed',
    ]);
}

public function test_order_is_processed()
{
    $order = Order::factory()->create();

    dispatch(new ProcessOrderJob($order));

    $this->assertDatabaseHas('orders', [
        'id' => $order->id,
        'status' => 'processed',
    ]);
}

With DatabaseTransactions

• job may not see the order
• test fails unexpectedly

With RefreshDatabase

• data is committed
• job works correctly
• test passes

Recommended Strategy

For most Laravel applications, the safest default is:

use RefreshDatabase;

use RefreshDatabase;

Then optimize later if needed.

Hybrid approach (advanced)

You can:

• use RefreshDatabase for feature tests
• use DatabaseTransactions for isolated unit-like tests

This gives you:

• reliability where needed
• speed where possible

Final Thoughts

Database testing in Laravel isn’t just about writing assertions — it’s about controlling state.

Choosing between RefreshDatabase and DatabaseTransactions directly affects:

• test reliability
• debugging time
• overall confidence in your application

If you’re unsure which one to use, start with:

RefreshDatabase

It may be slightly slower, but it will save you hours of debugging and prevent subtle, hard-to-track issues.

Once your test suite grows, you can selectively introduce DatabaseTransactions where performance matters and constraints are well understood.

TL;DR

• Use RefreshDatabase for reliability and real-world scenarios
• Use DatabaseTransactions for speed in simple cases
• Avoid mixing both
• Be mindful of queues and async behavior

A well-structured test suite isn’t just about coverage — it’s about trust.

And that trust starts with a clean, predictable database.

The post Laravel RefreshDatabase vs DatabaseTransactions: When to Use Each appeared first on CodeCraft Diary.