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.