top of page

How to run PHPUnit in Laravel?

Updated: Oct 3, 2023

Running PHPUnit in Laravel 5.5 allows you to test your application's code and ensure its correctness. PHPUnit is a popular testing framework for PHP, and Laravel provides convenient methods to run it within the framework. Below, I'll explain in detail the different methods and options for running PHPUnit tests in Laravel 5.5.

Run PHPUnit in Laravel

What is PHPUnit?

PHPUnit is a unit testing framework that allows developers to write test cases to evaluate individual components, methods, and functions within a PHP application. In the context of Laravel, PHPUnit is often used for testing various aspects of Laravel applications, including controllers, models, routes, and other components.

Key features and functions of PHPUnit in Laravel include:

  1. Test Suites: PHPUnit enables you to organize your tests into suites, making it easy to run specific groups of tests.

  2. Assertions: PHPUnit provides a wide range of assertion methods that allow you to verify that the code under test behaves as expected. Common assertions include checking for equality, asserting that exceptions are thrown, and verifying that specific conditions are met.

  3. Fixtures: PHPUnit supports the concept of fixtures, which are used to set up a known initial state for your tests. This ensures that your tests start with a consistent environment.

  4. Data Providers: PHPUnit allows you to use data providers to run the same test method with multiple sets of data, making it easy to test various input scenarios.

  5. Mocking and Stubbing: PHPUnit includes features for creating mocks and stubs, which are essential for isolating the code you want to test from external dependencies, such as databases or external services.

  6. Test Coverage: PHPUnit can generate code coverage reports, helping you identify which parts of your codebase are covered by tests and which are not.

How to run PHPUnit in Laravel?

In Laravel, PHPUnit is included by default as a development dependency, and Laravel provides a testing environment and a variety of helpful testing utilities. Laravel's testing framework builds on top of PHPUnit, offering additional features for testing HTTP requests, databases, and other Laravel-specific functionality.

Developers use PHPUnit in Laravel to write unit tests, integration tests, and feature tests, ensuring that their applications function correctly, remain maintainable, and continue working as expected as new code is added or modified. These tests contribute to the overall reliability and quality of Laravel applications.

To run PHPUnit in Laravel 5.5, you can use the following methods:

1. Using the 'vendor/bin/phpunit' command

The vendor/bin/phpunit command is the simplest and most straightforward way to run PHPUnit in Laravel 5.5. This command leverages the PHPUnit configuration file specific to your Laravel project and executes all tests defined in your application.

Here are the steps to use this method:

STEP 1: Open the terminal windows.

STEP 2: Navigate to the root directory of your Laravel project

STEP 3: Run the following command:


This command will locate and execute all the test files in your Laravel project.

What happens when you run vendor/bin/phpunit?

  • When you run this command, Laravel automatically locates and uses the PHPUnit configuration file specific to your project. This configuration file, often named phpunit.xml, is found in the root directory of your Laravel project. It contains settings and options for PHPUnit.

  • PHPUnit will then discover and execute all test classes and methods defined in your Laravel application.

  • PHPUnit provides detailed feedback on test results, including which tests passed, which failed, and any errors encountered during testing.

  • You can customize the PHPUnit configuration in the phpunit.xml file to suit your testing needs, such as specifying test directories, database connections, and other testing environment settings.

2. Using the php artisan test command

Laravel provides a convenient wrapper for PHPUnit through the php artisan test command. This command simplifies running PHPUnit tests and offers some additional options.

Here's how to use it:

php artisan test 

This command is essentially a wrapper for vendor/bin/phpunit and runs all tests in your Laravel application.

Advantages of using php artisan test:

  • Convenience: The php artisan test command is a Laravel-specific wrapper for PHPUnit, making it easy to run tests within the Laravel environment.

  • Laravel's Testing Helpers: Laravel provides helpful testing helpers and features that integrate seamlessly with PHPUnit. These include methods for database testing, making HTTP requests, and managing the application's testing environment.

  • Running PHPUnit from within Laravel allows you to use Laravel-specific features like testing routes, middleware, and authentication.

3. Running specific tests or groups of tests

If you want to run specific tests or groups of tests, Laravel provides options to filter and group your tests using the php artisan test command.

Running a specific test:

To run a specific test, use the --filter option followed by the name of the test class. For example, if you have a test class named TestExample, you can run it with the following command:

php artisan test --filter=TestExample 

Running a specific test with --filter:

  • The --filter option allows you to execute only a single test class or even a specific test method within a class.

  • For example, if you have a test class named TestExample and want to run only the testSomething method from it, you can use.

php artisan test --filter=TestExample::testSomething

Running tests within a group:

You can also run tests grouped by using the --group option. For instance, if you have a group of tests named Feature, you can run all tests within this group with the following command:

php artisan test --group=Feature 

Groups provide a way to categorize your tests. You can use the --group option to execute all tests within a specific group.

Excluding specific tests or groups:

To exclude specific tests or groups from being run, use the --exclude option. For example, to exclude the TestExample test from execution, you can use the following command:

php artisan test --exclude=TestExample 

4. Running PHPUnit in debug mode

Debugging tests can be essential for identifying and fixing issues. To run PHPUnit in debug mode, use the --debug option with the php artisan test command. This enables the PHPUnit debugger and allows you to step through your tests and inspect variable values.

Here's how to run PHPUnit in debug mode:

php artisan test --debug 

Running PHPUnit in debug mode enables you to set breakpoints, step through your tests, and inspect variable values at runtime.

Debugging can be invaluable when you encounter issues during testing and need to understand why a test is failing or identify problems in your application code.


Let's use the php artisan test command to run specific tests or groups of tests in Laravel. In this example, we'll demonstrate how to run a specific test using the --filter option.

Suppose you have a Laravel project with a test class named TestExample. We want to run the testExample method from this test class.

STEP 1: Open a terminal window.

STEP 2: Navigate to the root directory of your Laravel project.

STEP 3: Use the php artisan test command with the --filter option to run the specific test:

php artisan test --filter=TestExample::testExample

Here's what the relevant code and test file might look like:

Example Laravel Test Class (TestExample.php):


namespace Tests\Unit;

use Tests\TestCase;

class TestExample extends TestCase{
     * A basic test example.
     * @return void
     */public function testExample()
        // Your test logic goes here
        $this->assertTrue(true); // This is just a sample assertion

In this example, we've assumed a simple test class named 'TestExample'. Running the 'php artisan test --filter=TestExample::testExample' command will execute the testExample method within this class. You can replace the assertion inside the test method with your actual test logic.

Remember to replace 'TestExample' and 'testExample' with the appropriate class and method names from your project.


Running PHPUnit in Laravel is crucial for ensuring the reliability and quality of your Laravel applications. We explored methods like vendor/bin/phpunit and php artisan test, along with options to run specific tests or groups and enabling debug mode.


bottom of page