Nielsen Dev Notes

Appearance

Return to top
On this page

Running Tests in PHPStorm with Laravel Sail

This guide explains how to configure PHPStorm to run PHPUnit tests inside your Laravel Sail Docker container. This allows you to run tests directly from the IDE with a single click.

Prerequisites

  • PHPStorm installed
  • Laravel project with Sail configured
  • Sail container running (./vendor/bin/sail up -d)

Step 1: Add a CLI Interpreter

First, you need to configure PHPStorm to use the PHP interpreter from your Docker container.

  1. Open Settings (Ctrl+Alt+S)
  2. Navigate to PHP → CLI Interpreter
  3. Click the + button to add a new interpreter

Add CLI Interpreter

Step 2: Select Docker Compose

In the interpreter selection dialog:

  1. Click From Docker, Vagrant, VM, WSL, Remote...

From Docker Option

Step 3: Configure Docker Compose

  1. Select Docker Compose as the type
  2. Set Configuration files to ./compose.yaml (or docker-compose.yml for older projects)
  3. Select laravel.test as the service

Select Service

Step 4: Confirm Configuration

Review the settings and click OK:

  • Server: Docker
  • Service: laravel.test
  • PHP interpreter path: php

Docker Compose Config

Step 5: Final Interpreter Settings

Make sure to select Connect to existing container under Lifecycle. This ensures PHPStorm uses your already running Sail container instead of starting a new one each time.

Interpreter Configured

Step 6: Configure Test Framework (Optional)

If PHPStorm doesn't automatically detect PHPUnit:

  1. Go to Settings → PHP → Test Frameworks
  2. Add a new PHPUnit configuration
  3. Select your Docker interpreter
  4. Set the path to PHPUnit (usually vendor/autoload.php)

Test Framework Settings

Running Tests

Once configured, you can run tests directly from the editor:

  • Click the green play button next to a test class or method
  • Use Ctrl+Shift+R to run the test at cursor
  • Right-click on a test file and select Run

Run Test

Troubleshooting

Tests fail with "Connection refused"

Make sure your Sail container is running:

bash
./vendor/bin/sail up -d

PHPStorm starts a new container instead of using existing one

Verify that Connect to existing container is selected in the CLI Interpreter settings (Step 5).

Cannot find PHPUnit

Ensure PHPUnit is installed in your project:

bash
./vendor/bin/sail composer require --dev phpunit/phpunit