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 usesCONCAT() - Date formatting: SQLite uses
strftime(), MySQL usesDATE_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=3The 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.testingWhy 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: secretYou 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: secretIn 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.
