Pest Plugin Mysql Compat Laravel Package

Getting Started

jeffersongoncalves/pest-plugin-mysql-compat is a Pest plugin that helps you catch SQLite-vs-MySQL drift in your test suite. Because Laravel projects typically run tests against SQLite in-memory while production runs MySQL, this plugin exists to surface the queries, migrations, and JSON/function behaviour that silently diverge between the two drivers.

Minimal setup:

composer require --dev jeffersongoncalves/pest-plugin-mysql-compat

Register the plugin in your tests/Pest.php (Pest 2 auto-discovers plugins, but explicit registration is safer across versions):

uses(JeffersonGoncalves\PestMysqlCompat\...::class)->in('Feature', 'Unit');

Where to look first:

• The package README for the config file publication command (php artisan vendor:publish --tag=... if present).
• tests/Pest.php once installed — the plugin usually exposes helper functions or expect() extensions there.
• Your phpunit.xml / pest.xml for the database connection the compat checks use.

First use case: run your existing Pest suite and then the plugin's compat assertions against a real MySQL connection (e.g. a mysql_testing database) so you can see which of your "passing on SQLite" tests actually fail on the production driver. Start with a single feature test file before enabling it suite-wide — this keeps the first run fast and lets you judge the signal-to-noise.

Implementation Patterns

Dual-driver test runs. The most valuable workflow is a matrix: run the same Pest suite against SQLite locally and MySQL in CI. The plugin gives you the expectations/assertions to make that comparison meaningful (e.g. asserting a query or migration behaves equivalently on both). Keep both connections defined and switch via env:

// phpunit.xml
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_CONNECTION_MYSQL" value="mysql"/>

Targeted compat assertions. Rather than converting every test, reach for compat expectations on the tests most likely to drift: JSON column queries (whereJsonContains), upsert, enum columns, fulltext indexes, date functions (DATE_FORMAT, DATEDIFF), and raw DB::select() calls. Wrap these in a dedicated tests/Feature/Compatibility/ folder so the suite stays organised.

Migrations and raw SQL. Point the plugin at your migration set to verify schema definitions translate cleanly — this catches the classic "works on SQLite, breaks on MySQL 8" issues (default string lengths, unsigned columns, enum vs. check constraints) before they reach production.

CI integration. Add a separate job (or a Pest "group") that runs against MySQL so the slow driver doesn't block the fast local loop:

./vendor/bin/pest --group=mysql-compat

Use --filter or a Pest group to scope it, and keep the MySQL service container healthy in your workflow (health checks + wait-for-it-style step) so flaky connection errors don't mask real failures.

Data source of truth. Treat the MySQL run as canonical for anything touching the schema or advanced query builder features; the SQLite run remains your fast feedback loop.

Gotchas and Tips

• SQLite is not MySQL — that's the point, but it's also the trap. Passing the plugin locally is not a substitute for a real MySQL CI run. The plugin can detect drift, but you still need a MySQL instance somewhere to detect it against.
• MySQL version sensitivity. Behaviour differs between MySQL 5.7, 8.0, and MariaDB (JSON handling, utf8mb4 defaults, generated columns). Pin the version in CI and in any docker-compose setup; an unpinned mysql:latest will cause intermittent compat failures.
• Performance. MySQL-backed tests are noticeably slower than SQLite in-memory. Never enable compat checks across the whole suite by default in the local dev loop — gate them behind a group or an env flag.
• Transactions and isolation. If your compat tests use RefreshDatabase against MySQL, confirm the plugin's setup doesn't conflict with the trait's transaction wrapping. Nested transactions on MySQL behave differently from SQLite; explicit RefreshDatabase config in Pest.php is often required.
• Debugging a failing compat assertion. The plugin's failure messages can be terse. When a query fails, log the raw SQL with DB::listen() and compare the two dialects directly — this is usually faster than reading the assertion output.
• Config quirks. The 1.0.0 release notes are effectively empty (just a changelog link), so treat the README and the source as the contract. Read the config file immediately after publishing rather than assuming defaults; the connection name and driver settings are the most common misconfiguration.
• Extension points. Because it's a Pest plugin, you can compose it with your own custom expect() extensions — extend the plugin's expectations rather than forking it. Check the plugin's service provider for bindings you can override if you need custom normalisation.
• Version pinning. As a fresh 1.0.0 with no documented upgrade story yet, pin to ^1.0 in composer.json and review the changelog before bumping. There's no migration/upgrade guide published, so a minor bump could still introduce behavioural changes to assertions.
• Don't let it become a crutch. The strongest long-term fix is to run integration tests against MySQL in CI anyway; use the plugin to find the drift, then eliminate the drift rather than permanently tolerating compat warnings.