Test-Driven Laravel: Integrating PHPUnit, Pest, and Continuous Integration

Want to build reliable Laravel apps faster? Test-Driven Development (TDD) is the key. Write tests first, code later, and catch bugs early. Here’s how to do it with Laravel’s PHPUnit and Pest frameworks, plus Continuous Integration (CI) for automated testing.

Key Takeaways:

TDD Process: Write failing tests → add code to pass → refine.
Frameworks: PHPUnit (object-oriented, robust assertions) vs. Pest (clean syntax, easier to learn).
CI Benefits: Automate testing, catch bugs early, and ensure consistent code quality.
Setup Essentials:
- Configure PHPUnit and Pest for Laravel.
- Use .env.testing for isolated environments.
- Leverage factories for test data.
CI Integration: Automate tests with GitHub Actions or similar tools to save time and improve quality.

Quick Comparison:

Feature	PHPUnit	Pest
Syntax Style	Object-oriented	Functional
Learning Curve	Moderate	Gentle
Test Organization	Class-based	File-based
Dataset Support	Data Providers	Built-in datasets

Start small: test critical features, automate with CI, and monitor coverage for better results. Ready to level up your Laravel testing? Let’s dive in.

Test Driven Development with Pest PHP

Test Environment Setup

Build a solid testing environment for Laravel TDD to ensure your tests are reliable and easily integrated into your CI pipeline.

PHPUnit Configuration

Laravel includes PHPUnit pre-configured. Check the phpunit.xml file in your project root to make sure it's set up correctly:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit colors="true"
         cacheResult="false"
         backupGlobals="false"
         processIsolation="false"
         stopOnFailure="false">
    <testsuites>
        <testsuite name="Unit">
            <directory suffix="Test.php">./tests/Unit</directory>
        </testsuite>
        <testsuite name="Feature">
            <directory suffix="Test.php">./tests/Feature</directory>
        </testsuite>
    </testsuites>
    <coverage>
        <include>
            <directory suffix=".php">./app</directory>
        </include>
    </coverage>
</phpunit>

Set up a dedicated test database to keep your tests isolated from your main application:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_testing
DB_USERNAME=root
DB_PASSWORD=

Adding Pest to Your Project

To use Pest alongside PHPUnit, install it via Composer:

composer require pestphp/pest --dev
composer require pestphp/pest-plugin-laravel --dev
php artisan pest:install

Organize your test files into the following directories for better structure:

Directory	Purpose	Test Types
tests/Unit	Unit tests	Classes, Methods
tests/Feature	Feature tests	API, Routes
tests/Integration	Integration tests	Services, Components

Configuring the Testing Environment

Create a .env.testing file to define environment variables specific to testing:

APP_ENV=testing
DB_CONNECTION=sqlite
DB_DATABASE=:memory:
CACHE_DRIVER=array
SESSION_DRIVER=array
QUEUE_DRIVER=sync

Update your config/database.php file to include a testing database connection:

'connections' => [
    'testing' => [
        'driver' => 'sqlite',
        'database' => ':memory:',
        'prefix' => '',
    ],
]

Setting Up Test Factories

Use test factories in database/factories to generate consistent test data. Here's an example for a UserFactory:

namespace Database\Factories;

use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;

class UserFactory extends Factory
{
    protected $model = User::class;

    public function definition()
    {
        return [
            'name' => $this->faker->name(),
            'email' => $this->faker->unique()->safeEmail(),
            'password' => bcrypt('password'),
        ];
    }
}

Refreshing the Test Database

To ensure a clean slate for each test suite, refresh the database before running tests:

use RefreshDatabase;

class ExampleTest extends TestCase
{
    use RefreshDatabase;

    public function test_example()
    {
        // Your test code here
    }
}

With this setup, you’re ready to write and organize tests using both PHPUnit and Pest in the next steps.

Creating Tests with PHPUnit and Pest

Laravel Test Structure

When working with Laravel, it's important to organize your test files based on their purpose. Begin by extending Laravel's TestCase in your test classes. Here's an example:

use Tests\TestCase;
use App\Models\User;

class UserTest extends TestCase
{
    public function test_user_can_be_created()
    {
        $userData = [
            'name' => 'John Doe',
            'email' => '[email protected]',
            'password' => 'secure123'
        ];

        $user = User::create($userData);

        $this->assertDatabaseHas('users', [
            'email' => '[email protected]'
        ]);
    }
}

For better clarity and maintainability, follow the Arrange-Act-Assert pattern in your test methods:

public function test_user_can_update_profile()
{
    // Arrange
    $user = User::factory()->create();
    $newData = ['name' => 'Jane Doe'];

    // Act
    $user->update($newData);

    // Assert
    $this->assertEquals('Jane Doe', $user->fresh()->name);
}

Once you've mastered PHPUnit, you can take advantage of Pest's simpler and more concise syntax for writing tests.

Writing Tests with Pest

Pest offers a streamlined way to write tests. Here's an example of creating a user with Pest:

use App\Models\User;

test('user can be created', function () {
    $userData = [
        'name' => 'John Doe',
        'email' => '[email protected]',
        'password' => 'secure123'
    ];

    $user = User::create($userData);

    expect($user)->toBeInstanceOf(User::class)
        ->and($user->email)->toBe('[email protected]');
});

You can also test specific functionalities, like sending a welcome email after user registration:

test('sends welcome email after registration', function () {
    Mail::fake();
    User::factory()->create();
    Mail::assertSent(WelcomeEmail::class);
});

Test Organization Methods

Pest allows you to group tests using describe blocks, making it easier to organize related tests:

describe('User Registration', function () {
    beforeEach(function () {
        Mail::fake();
    });

    it('creates new user account', function () {
        // Test implementation
    });

    it('validates required fields', function () {
        // Test implementation
    });
});

For reusable test data, leverage Laravel's model factories. Here's an example of creating dedicated test datasets:

class UserTest extends TestCase
{
    private function createTestUser(): User
    {
        return User::factory()->create([
            'email_verified_at' => now(),
            'role' => 'customer'
        ]);
    }

    private function createAdminUser(): User
    {
        return User::factory()->create([
            'email_verified_at' => now(),
            'role' => 'admin'
        ]);
    }
}

You can also use Pest's dataset feature to validate multiple scenarios:

test('validates user roles', function ($role, $expected) {
    $user = User::factory()->create(['role' => $role]);
    expect($user->hasValidRole())->toBe($expected);
})->with([
    ['admin', true],
    ['user', true],
    ['invalid', false],
]);

Finally, structure your test files to align with your application's architecture for better clarity. Here's a suggested structure:

Test Type	Location	Purpose
Unit Tests	`tests/Unit/Services`	Test individual service classes
Feature Tests	`tests/Feature/Auth`	Test authentication flows
Integration Tests	`tests/Integration/Api`	Test API endpoints
Browser Tests	`tests/Browser`	Test UI interactions

Monitor Your Test Quality

With OtterWise, you can track Code Coverage, contributor stats, code quality, and much more.

Start improving your code quality

Free for open source

Setting Up CI for Automated Tests

Choosing a CI Platform

Pick a CI platform that works well with Laravel testing. GitHub Actions is a great option because it integrates smoothly with GitHub repositories and offers a variety of marketplace actions. Your chosen platform should support:

PHP versions
Composer for managing dependencies
Databases like MySQL or PostgreSQL
Redis for cache testing
Setting up environment variables

Here’s an example configuration for GitHub Actions:

name: Laravel Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_DATABASE: laravel_test
          MYSQL_ROOT_PASSWORD: password
        ports:
          - 3306:3306

    steps:
      - uses: actions/checkout@v3
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: mbstring, dom, fileinfo, mysql

Once you’ve selected your platform, set up your pipeline to automate testing.

Configuring the CI Pipeline

Your CI workflow should handle installing dependencies, running migrations, and executing tests automatically. Here’s an example configuration:

steps:
  - name: Copy .env
    run: cp .env.example .env

  - name: Install Dependencies
    run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist

  - name: Generate key
    run: php artisan key:generate

  - name: Run Database Migrations
    run: php artisan migrate --force

  - name: Execute Tests
    run: vendor/bin/pest --parallel

Using Pest for parallel testing can help cut down on test execution time.

Adding OtterWise for Coverage Tracking

OtterWise

To enhance your pipeline, integrate OtterWise for tracking code coverage. Follow these steps:

Install the OtterWise GitHub App in your repository.
Update your CI pipeline to generate and upload coverage reports.
Configure status checks for pull requests.

Here’s an example of how to generate and upload coverage reports:

- name: Generate Coverage Report
  run: vendor/bin/pest --coverage --coverage-clover=build/logs/clover.xml

- name: Upload Coverage
  env:
    OTTERWISE_TOKEN: ${{ secrets.OTTERWISE_TOKEN }}
  run: bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh)

OtterWise’s Pro plan starts at $9 per month, offering features like unlimited data history and mutation testing. Public repositories can use basic coverage tracking for free.

To enforce code quality, set up status checks:

status_checks:
  coverage:
    minimum: 80
    paths:
      - 'app/**/*.php'
      - 'src/**/*.php'
    exclude:
      - 'tests/**'

This configuration ensures that new code maintains at least 80% coverage. Pull requests that don’t meet this requirement will be blocked.

Advanced TDD Techniques

Feature Development with TDD

In Laravel TDD, start by writing tests that outline the expected behavior before any coding begins. For instance, when building a user registration feature, you could write a test like this:

public function test_user_registration()
{
    $response = $this->post('/register', [
        'name' => 'John Doe',
        'email' => '[email protected]',
        'password' => 'SecurePass123',
        'password_confirmation' => 'SecurePass123'
    ]);

    $this->assertDatabaseHas('users', [
        'email' => '[email protected]'
    ]);

    $response->assertRedirect('/dashboard');
}

Once the test fails (as expected), write just enough code to make it pass. This approach helps clarify requirements and avoids unnecessary complexity.

Beyond developing features, expanding your test coverage ensures the overall reliability of your application.

Code Coverage Improvement

Use tools like OtterWise for automated code coverage analysis. You can configure your phpunit.xml file to exclude less critical files and focus on the core application:

<coverage>
    <include>
        <directory suffix=".php">app</directory>
    </include>
    <exclude>
        <directory>app/Console</directory>
        <directory>app/Exceptions</directory>
    </exclude>
</coverage>

To boost coverage efficiently, consider the following:

Focus on critical areas: Prioritize testing features like authentication, payments, validations, and APIs.

Use data providers for multiple scenarios: This allows you to test various cases without duplicating code.

public function provideUserData()
{
    return [
        'valid_user' => [
            'name' => 'Jane Doe',
            'email' => '[email protected]',
            'expected' => true
        ],
        'invalid_email' => [
            'name' => 'John Smith',
            'email' => 'invalid-email',
            'expected' => false
        ]
    ];
}

Test edge cases and validation errors: For example, handle inputs that exceed limits or fail validation.

public function test_user_creation_with_validation()
{
    $response = $this->post('/users', [
        'name' => str_repeat('a', 256), // Too long
        'email' => 'invalid-email'
    ]);

    $response->assertStatus(422)
        ->assertJsonValidationErrors(['name', 'email']);
}

OtterWise helps by adding actionable feedback directly to pull requests, making it easier to spot untested code and maintain thorough coverage throughout your development process.

Conclusion

Test-Driven Development (TDD) in Laravel, combined with advanced testing tools and Continuous Integration (CI), can greatly enhance the quality of your development process.

TDD helps improve code reliability, speeds up development, and minimizes technical debt. By ensuring proper test coverage and automating processes, teams can spend less time fixing bugs and more time building features, all while maintaining high standards.

With tools like OtterWise, you can gain insights into test coverage and automate pull request checks, allowing your team to focus on delivering features without compromising on testing quality.

Start small with TDD - focus on critical features first, gradually extend test coverage, and use automation to maintain consistency. This method not only keeps maintenance costs under control but also increases development speed, forming a solid foundation for Laravel projects.