Run Laravel Pest Tests Against MySQL in GitHub Actions

This is the post I wish existed when I was first setting up CI. The official docs show you how to add a MySQL service container. What they don’t show you is the three silent ways your tests will still fail even after you’ve done everything right.

I’ll show you all of them.

Why Not SQLite?

SQLite is the default for Laravel tests because it’s fast and needs no setup. For unit tests that don’t touch the database, it’s fine. For feature tests it creates a subtle trap.

SQLite has different SQL than MySQL. Specifically:

• String concatenation: SQLite uses ||, MySQL uses CONCAT()
• Date formatting: SQLite uses strftime(), MySQL uses DATE_FORMAT()
• Column ambiguity rules are more lenient in SQLite
• Some JSON functions differ

If your Eloquent queries ever touch raw SQL (in selectRaw, whereRaw, orderByRaw, report queries), SQLite will pass them and MySQL will reject them. You won’t find out until production.

Run your tests against MySQL. The extra setup is 20 lines of YAML.

Step 1: Add the MySQL Service

In your api-ci.yml, add a services: block to your test job:

  tests:
    name: Tests (PHP 8.4, MySQL 8.4)
    runs-on: ubuntu-latest

    services:
      mysql:
        image: mysql:8.4
        env:
          MYSQL_DATABASE: your_app_test
          MYSQL_ROOT_PASSWORD: secret
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3

The options: block makes GitHub Actions wait for MySQL to actually be ready before running your steps. Without it, your migration step will try to connect to MySQL before it’s accepting connections and fail with a confusing error.

Step 2: Override the Test Environment

GitHub Actions doesn’t use your local .env or .env.testing. You set environment variables explicitly. The cleanest pattern is to copy .env.example into .env.testing and then append overrides:

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

      - name: Set test environment variables
        run: |
          echo "APP_ENV=testing" >> .env.testing
          echo "APP_KEY=base64:$(openssl rand -base64 32)" >> .env.testing
          echo "DB_CONNECTION=mysql" >> .env.testing
          echo "DB_HOST=127.0.0.1" >> .env.testing
          echo "DB_PORT=3306" >> .env.testing
          echo "DB_DATABASE=your_app_test" >> .env.testing
          echo "DB_USERNAME=root" >> .env.testing
          echo "DB_PASSWORD=secret" >> .env.testing
          echo "QUEUE_CONNECTION=sync" >> .env.testing
          echo "BROADCAST_CONNECTION=log" >> .env.testing
          echo "CACHE_STORE=array" >> .env.testing

Why BROADCAST_CONNECTION=log? This one burned me. If your .env.example has BROADCAST_CONNECTION=reverb (the default since Laravel 11), any test that fires a broadcast event — a payment completed, a status changed, a notification sent — will try to open a TCP connection to 0.0.0.0:8080. There’s no Reverb server in CI. Every such request returns 500. Your tests fail with no obvious explanation. Setting it to log routes broadcast events to the log file instead.

Why QUEUE_CONNECTION=sync? Queued jobs run immediately inline instead of being pushed to Redis. Without this, any controller action that dispatches a job will silently not execute it during tests.

Step 3: Migrate and Test

      - name: Run migrations
        run: php artisan migrate --env=testing --force
        env:
          DB_CONNECTION: mysql
          DB_HOST: 127.0.0.1
          DB_PORT: "3306"
          DB_DATABASE: your_app_test
          DB_USERNAME: root
          DB_PASSWORD: secret

      - name: Run Pest tests
        run: ./vendor/bin/pest
        env:
          DB_CONNECTION: mysql
          DB_HOST: 127.0.0.1
          DB_PORT: "3306"
          DB_DATABASE: your_app_test
          DB_USERNAME: root
          DB_PASSWORD: secret

You pass the DB env vars twice — once to the migrate step and once to the test step. Each step in GitHub Actions runs in a fresh shell, so being explicit here avoids surprises.

The Empty Directory Trap

Git doesn’t track empty directories. If your tests rely on storage/framework/views/, storage/framework/sessions/, or bootstrap/cache/ existing, they’ll be missing in a fresh CI checkout.

Laravel’s package:discover (which runs after composer install) boots the framework, which needs these directories. If they don’t exist, the whole setup step crashes with a cryptic “Please provide a valid cache path” error.

Fix: add a .gitignore placeholder in each required directory:

for dir in \
  storage/framework/views \
  storage/framework/sessions \
  storage/framework/cache/data \
  storage/logs \
  bootstrap/cache; do
  mkdir -p api/$dir
  printf "*\n!.gitignore" > api/$dir/.gitignore
done
git add api/storage api/bootstrap/cache
git commit -m "chore: add storage skeleton for CI"

The Empty Test Directory Trap

Pest exits with code 2 (not 1) when a configured test directory doesn’t exist. If your phpunit.xml lists tests/Unit but that directory is empty and never committed, CI fails before running a single test.

The fix isn’t to add a .gitkeep. The fix is to add at least one meaningful test in every directory you configure in phpunit.xml. CI failing before tests run is uninformative; CI failing on a real assertion tells you exactly what broke.

Full Test Job Reference

  tests:
    name: Tests (PHP 8.4, MySQL 8.4)
    runs-on: ubuntu-latest
    needs: quality

    services:
      mysql:
        image: mysql:8.4
        env:
          MYSQL_DATABASE: your_app_test
          MYSQL_ROOT_PASSWORD: secret
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP 8.4
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          extensions: mbstring, pdo, pdo_mysql, bcmath, gd, zip, intl
          coverage: none
          tools: composer:v2

      - name: Cache Composer dependencies
        uses: actions/cache@v4
        with:
          path: api/vendor
          key: php-8.4-composer-${{ hashFiles('api/composer.lock') }}
          restore-keys: php-8.4-composer-

      - name: Install dependencies
        run: composer install --no-interaction --prefer-dist --no-progress

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

      - name: Set test environment variables
        run: |
          echo "APP_ENV=testing" >> .env.testing
          echo "APP_KEY=base64:$(openssl rand -base64 32)" >> .env.testing
          echo "DB_CONNECTION=mysql" >> .env.testing
          echo "DB_HOST=127.0.0.1" >> .env.testing
          echo "DB_PORT=3306" >> .env.testing
          echo "DB_DATABASE=your_app_test" >> .env.testing
          echo "DB_USERNAME=root" >> .env.testing
          echo "DB_PASSWORD=secret" >> .env.testing
          echo "QUEUE_CONNECTION=sync" >> .env.testing
          echo "BROADCAST_CONNECTION=log" >> .env.testing
          echo "CACHE_STORE=array" >> .env.testing

      - name: Run migrations
        run: php artisan migrate --env=testing --force
        env:
          DB_CONNECTION: mysql
          DB_HOST: 127.0.0.1
          DB_PORT: "3306"
          DB_DATABASE: your_app_test
          DB_USERNAME: root
          DB_PASSWORD: secret

      - name: Run Pest tests
        run: ./vendor/bin/pest
        env:
          DB_CONNECTION: mysql
          DB_HOST: 127.0.0.1
          DB_PORT: "3306"
          DB_DATABASE: your_app_test
          DB_USERNAME: root
          DB_PASSWORD: secret

In the next post we add the code quality gate that runs before tests and blocks any PR that has style drift or static-analysis errors.

Originally published at dineshstack.com — read the full version with code samples and updates there.