# Testing: Getting Started

  * Introduction
  * Environment
  * Creating Tests
  * Running Tests
    * Running Tests in Parallel
    * Reporting Test Coverage
    * Profiling Tests

## Introduction

Laravel is built with testing in mind. In fact, support for testing with
[Pest](https://pestphp.com) and [PHPUnit](https://phpunit.de) is included out
of the box and a `phpunit.xml` file is already set up for your application.
The framework also ships with convenient helper methods that allow you to
expressively test your applications.

By default, your application's `tests` directory contains two directories:
`Feature` and `Unit`. Unit tests are tests that focus on a very small,
isolated portion of your code. In fact, most unit tests probably focus on a
single method. Tests within your "Unit" test directory do not boot your
Laravel application and therefore are unable to access your application's
database or other framework services.

Feature tests may test a larger portion of your code, including how several
objects interact with each other or even a full HTTP request to a JSON
endpoint. **Generally, most of your tests should be feature tests. These types
of tests provide the most confidence that your system as a whole is
functioning as intended.**

An `ExampleTest.php` file is provided in both the `Feature` and `Unit` test
directories. After installing a new Laravel application, execute the
`vendor/bin/pest`, `vendor/bin/phpunit`, or `php artisan test` commands to run
your tests.

## Environment

When running tests, Laravel will automatically set the [configuration
environment](/docs/12.x/configuration#environment-configuration) to `testing`
because of the environment variables defined in the `phpunit.xml` file.
Laravel also automatically configures the session and cache to the `array`
driver so that no session or cache data will be persisted while testing.

You are free to define other testing environment configuration values as
necessary. The `testing` environment variables may be configured in your
application's `phpunit.xml` file, but make sure to clear your configuration
cache using the `config:clear` Artisan command before running your tests!

#### The `.env.testing` Environment File

In addition, you may create a `.env.testing` file in the root of your project.
This file will be used instead of the `.env` file when running Pest and
PHPUnit tests or executing Artisan commands with the `--env=testing` option.

## Creating Tests

To create a new test case, use the `make:test` Artisan command. By default,
tests will be placed in the `tests/Feature` directory:

    
    
    1php artisan make:test UserTest
    
    
    php artisan make:test UserTest

If you would like to create a test within the `tests/Unit` directory, you may
use the `--unit` option when executing the `make:test` command:

    
    
    1php artisan make:test UserTest --unit
    
    
    php artisan make:test UserTest --unit

Test stubs may be customized using [stub publishing](/docs/12.x/artisan#stub-
customization).

Once the test has been generated, you may define test as you normally would
using Pest or PHPUnit. To run your tests, execute the `vendor/bin/pest`,
`vendor/bin/phpunit`, or `php artisan test` command from your terminal:

Pest PHPUnit

    
    
    1<?php
    
    2 
    
    3test('basic', function () {
    
    4    expect(true)->toBeTrue();
    
    5});
    
    
    <?php
    
    test('basic', function () {
        expect(true)->toBeTrue();
    });
    
    
     1<?php
    
     2 
    
     3namespace Tests\Unit;
    
     4 
    
     5use PHPUnit\Framework\TestCase;
    
     6 
    
     7class ExampleTest extends TestCase
    
     8{
    
     9    /**
    
    10     * A basic test example.
    
    11     */
    
    12    public function test_basic_test(): void
    
    13    {
    
    14        $this->assertTrue(true);
    
    15    }
    
    16}
    
    
    <?php
    
    namespace Tests\Unit;
    
    use PHPUnit\Framework\TestCase;
    
    class ExampleTest extends TestCase
    {
        /**
         * A basic test example.
         */
        public function test_basic_test(): void
        {
            $this->assertTrue(true);
        }
    }

If you define your own `setUp` / `tearDown` methods within a test class, be
sure to call the respective `parent::setUp()` / `parent::tearDown()` methods
on the parent class. Typically, you should invoke `parent::setUp()` at the
start of your own `setUp` method, and `parent::tearDown()` at the end of your
`tearDown` method.

## Running Tests

As mentioned previously, once you've written tests, you may run them using
`pest` or `phpunit`:

Pest PHPUnit

    
    
    1./vendor/bin/pest
    
    
    ./vendor/bin/pest
    
    
    1./vendor/bin/phpunit
    
    
    ./vendor/bin/phpunit

In addition to the `pest` or `phpunit` commands, you may use the `test`
Artisan command to run your tests. The Artisan test runner provides verbose
test reports in order to ease development and debugging:

    
    
    1php artisan test
    
    
    php artisan test

Any arguments that can be passed to the `pest` or `phpunit` commands may also
be passed to the Artisan `test` command:

    
    
    1php artisan test --testsuite=Feature --stop-on-failure
    
    
    php artisan test --testsuite=Feature --stop-on-failure

### Running Tests in Parallel

By default, Laravel and Pest / PHPUnit execute your tests sequentially within
a single process. However, you may greatly reduce the amount of time it takes
to run your tests by running tests simultaneously across multiple processes.
To get started, you should install the `brianium/paratest` Composer package as
a "dev" dependency. Then, include the `--parallel` option when executing the
`test` Artisan command:

    
    
    1composer require brianium/paratest --dev
    
    2 
    
    3php artisan test --parallel
    
    
    composer require brianium/paratest --dev
    
    php artisan test --parallel

By default, Laravel will create as many processes as there are available CPU
cores on your machine. However, you may adjust the number of processes using
the `--processes` option:

    
    
    1php artisan test --parallel --processes=4
    
    
    php artisan test --parallel --processes=4

When running tests in parallel, some Pest / PHPUnit options (such as `--do-
not-cache-result`) may not be available.

#### Parallel Testing and Databases

As long as you have configured a primary database connection, Laravel
automatically handles creating and migrating a test database for each parallel
process that is running your tests. The test databases will be suffixed with a
process token which is unique per process. For example, if you have two
parallel test processes, Laravel will create and use `your_db_test_1` and
`your_db_test_2` test databases.

By default, test databases persist between calls to the `test` Artisan command
so that they can be used again by subsequent `test` invocations. However, you
may re-create them using the `--recreate-databases` option:

    
    
    1php artisan test --parallel --recreate-databases
    
    
    php artisan test --parallel --recreate-databases

#### Parallel Testing Hooks

Occasionally, you may need to prepare certain resources used by your
application's tests so they may be safely used by multiple test processes.

Using the `ParallelTesting` facade, you may specify code to be executed on the
`setUp` and `tearDown` of a process or test case. The given closures receive
the `$token` and `$testCase` variables that contain the process token and the
current test case, respectively:

    
    
     1<?php
    
     2 
    
     3namespace App\Providers;
    
     4 
    
     5use Illuminate\Support\Facades\Artisan;
    
     6use Illuminate\Support\Facades\ParallelTesting;
    
     7use Illuminate\Support\ServiceProvider;
    
     8use PHPUnit\Framework\TestCase;
    
     9 
    
    10class AppServiceProvider extends ServiceProvider
    
    11{
    
    12    /**
    
    13     * Bootstrap any application services.
    
    14     */
    
    15    public function boot(): void
    
    16    {
    
    17        ParallelTesting::setUpProcess(function (int $token) {
    
    18            // ...
    
    19        });
    
    20 
    
    21        ParallelTesting::setUpTestCase(function (int $token, TestCase $testCase) {
    
    22            // ...
    
    23        });
    
    24 
    
    25        // Executed when a test database is created...
    
    26        ParallelTesting::setUpTestDatabase(function (string $database, int $token) {
    
    27            Artisan::call('db:seed');
    
    28        });
    
    29 
    
    30        ParallelTesting::tearDownTestCase(function (int $token, TestCase $testCase) {
    
    31            // ...
    
    32        });
    
    33 
    
    34        ParallelTesting::tearDownProcess(function (int $token) {
    
    35            // ...
    
    36        });
    
    37    }
    
    38}
    
    
    <?php
    
    namespace App\Providers;
    
    use Illuminate\Support\Facades\Artisan;
    use Illuminate\Support\Facades\ParallelTesting;
    use Illuminate\Support\ServiceProvider;
    use PHPUnit\Framework\TestCase;
    
    class AppServiceProvider extends ServiceProvider
    {
        /**
         * Bootstrap any application services.
         */
        public function boot(): void
        {
            ParallelTesting::setUpProcess(function (int $token) {
                // ...
            });
    
            ParallelTesting::setUpTestCase(function (int $token, TestCase $testCase) {
                // ...
            });
    
            // Executed when a test database is created...
            ParallelTesting::setUpTestDatabase(function (string $database, int $token) {
                Artisan::call('db:seed');
            });
    
            ParallelTesting::tearDownTestCase(function (int $token, TestCase $testCase) {
                // ...
            });
    
            ParallelTesting::tearDownProcess(function (int $token) {
                // ...
            });
        }
    }

#### Accessing the Parallel Testing Token

If you would like to access the current parallel process "token" from any
other location in your application's test code, you may use the `token`
method. This token is a unique, string identifier for an individual test
process and may be used to segment resources across parallel test processes.
For example, Laravel automatically appends this token to the end of the test
databases created by each parallel testing process:

    
    
    1$token = ParallelTesting::token();
    
    
    $token = ParallelTesting::token();

### Reporting Test Coverage

This feature requires [Xdebug](https://xdebug.org) or
[PCOV](https://pecl.php.net/package/pcov).

When running your application tests, you may want to determine whether your
test cases are actually covering the application code and how much application
code is used when running your tests. To accomplish this, you may provide the
`--coverage` option when invoking the `test` command:

    
    
    1php artisan test --coverage
    
    
    php artisan test --coverage

#### Enforcing a Minimum Coverage Threshold

You may use the `--min` option to define a minimum test coverage threshold for
your application. The test suite will fail if this threshold is not met:

    
    
    1php artisan test --coverage --min=80.3
    
    
    php artisan test --coverage --min=80.3

### Profiling Tests

The Artisan test runner also includes a convenient mechanism for listing your
application's slowest tests. Invoke the `test` command with the `--profile`
option to be presented with a list of your ten slowest tests, allowing you to
easily investigate which tests can be improved to speed up your test suite:

    
    
    1php artisan test --profile
    
    
    php artisan test --profile