Test-Driven Development in Laravel: The Red-Green-Refacto...

We’ve all been there. You have a new feature to build. You open your IDE, create a Controller, start wiring up the logic, maybe add some validation, and then, hours later, you finally write a test to make sure it actually works. Or, if we’re being honest, maybe you don’t write the test at all.

This is the “code first, ask questions later” approach. And while it feels fast at the start, it’s exactly how we end up with legacy code that nobody dares to touch. It’s how “it works on my machine” turns into a 3:00 AM emergency production fix.

Test-Driven Development (TDD) flips this on its head. Instead of writing code to solve a problem and then writing tests to verify it, you write the test first. It sounds counterintuitive, but it’s a game-changer for maintainability. Let’s break it down into the cycle that actually defines professional software development: Red, Green, Refactor.

Previous article in this category: https://codecraftdiary.com/2026/06/01/flaky-tests-in-laravel/

The Cycle Explained: It’s a Rhythm, Not a Rule

The TDD process is a rhythmic loop that keeps you focused.

Red: You write a test for a tiny, specific piece of functionality that doesn’t exist yet. You run it. It should fail. If it passes immediately, your test is either broken or testing nothing.
Green: You write the absolute minimum amount of code to make that test pass. Not perfect code, not optimized code—just enough code.
Refactor: Now that you have a safety net, you clean up. You improve naming, extract methods, remove duplication, and optimize. Because you have the test, you can change the internals without breaking the contract.

The “Why”: Beyond Just Catching Bugs

Why go through the trouble? TDD is not just about catching bugs. It’s about design.

When you write the test first, you are forced to step into the shoes of the “consumer” of your code. You stop thinking about how a database table is structured and start thinking about how a controller or a service needs to interact with your business logic. If you find it hard to write a test, you’ve just received the most valuable feedback possible: your design is too complex or your coupling is too tight.

TDD acts as an early warning system for bad architecture.

A Real-World Example: Building a “Subscription System”

Let’s say we are building a subscription feature. We need to ensure that when a user subscribes, they receive a welcome email, and their status is updated in the database.

Phase 1: The Red Phase (The Requirement)

We start with a feature test. We are defining the behavior, not the implementation.

public function test_user_can_subscribe_to_a_plan()
{
    $user = User::factory()->create();

    $response = $this->actingAs($user)->post('/subscribe', [
        'plan_id' => 'premium_monthly'
    ]);

    $response->assertStatus(200);
    $this->assertDatabaseHas('subscriptions', [
        'user_id' => $user->id,
        'plan' => 'premium_monthly'
    ]);
}

Running this results in a 404 or an error, because the route doesn’t exist. Red.

Phase 2: The Green Phase (The Implementation)

Now, we write just enough code to make this pass. We might put all the logic in the controller (yes, even if it’s dirty, because that’s the “Green” phase).

public function store(Request $request)
{
    Subscription::create([
        'user_id' => auth()->id(),
        'plan' => $request->plan_id
    ]);
    return response()->json(['status' => 'success'], 200);
}

Test passes. Green.

Phase 3: The Refactor Phase (The Cleanup)
Now that the test is green, we look at the controller. It’s getting a bit crowded. We decide to move the logic into a SubscriptionService. We move the logic, run the test again—it still passes! We have total confidence that the refactoring didn’t break the core business requirement.

Deep Dive: Common Pitfalls

1. Over-Mocking

Developers often mock every single dependency, resulting in tests that pass even when the real system is broken. If you are mocking your entire application to test one controller, you aren’t testing reality. Use real database connections (via RefreshDatabase) and real events whenever possible.

2. Testing Implementation vs. Behavior

Don’t write tests that check if a private method was called or if a specific variable was set. Test the result. Did the user get the email? Did the database change? Does the UI show the right message? If you test the implementation, your tests will break every time you refactor, which defeats the whole purpose.

3. Avoiding the “Green” Trap

Sometimes, you write a test that is too big. You try to test the entire checkout flow in one test. When it fails, you don’t know why. Break it down. Test the validation of the payment, then the user status, then the email trigger. Small, focused tests are the secret to a high-speed suite.

The “Slow Down to Speed Up” Philosophy

The biggest pushback I hear is: “TDD takes twice as long.”

It feels like that at first. You are typing more code. You are thinking more. But think about the time you spend on:

Manual debugging sessions in the browser.
Writing “temporary” logging statements to trace data flow.
Fear of deploying because you don’t know what might break.

With TDD, that “debugging” time disappears. You catch the logic error within three seconds of writing it. That is where the speed comes from. TDD isn’t about writing code faster; it’s about shipping with confidence because your test suite is your documentation.

Final Thoughts for 2026

Modern Laravel development is about clean, maintainable logic. If you want to survive a project that grows over several years, you cannot rely on memory or manual testing.

TDD isn’t a religion; it’s a discipline. Start today. Pick one small class or service. Write the test, watch it fail, and then write the code to fix it. Over time, it won’t feel like “work”—it will feel like having a second pair of eyes constantly reviewing your code as you type.

Happy coding.

推荐订阅源

DEV Community