Health-insurance admin app: rescuing Laravel 5.6 with tests first
A health-insurance administration app that had not been upgraded in six years, running Laravel 5.6 on a client intranet with no documentation and no tests. We wrote the tests first, then upgraded Laravel one major version at a time, from 5.6 to 13, with the suite green at every step.
RESULTA six-year-old, 20k-line Laravel 5.6 app taken to Laravel 13 on PHP 8.4 in 1 week, one major version at a time, with 80% test coverage and no change to how staff work.
- Characterization tests
- Laravel upgrades
- PHP upgrade
- Documentation
“Our claims system had run untouched on Laravel 5.6 for six years. Nobody dared change it, and there was no documentation or a single test. Vasuttam first wrote tests that captured how the app actually behaves, then upgraded it step by step to Laravel 13 on PHP 8.4. The whole job took one week, and our staff didn't notice a thing, except that it's now safe to change.”
- Laravel 5.6
- Starting point
- Laravel 13 · PHP 8.4
- Now on
- ~20k lines
- Codebase
- 1 week
- Time taken
- 6
- Years without upgrades
- 80%
- Test coverage before upgrading
- None
- Docs and tests at start
The app manages members, their health policies, invoices and claims for the client's staff, and it had been running untouched on Laravel 5.6 inside the client's intranet for six years. Nobody who built it was around, there was no documentation, and there was not a single test to show what the app was supposed to do. Every change was a guess, and the framework and PHP version were long out of security support.
- Test coverage taken from zero to 80% before any framework code was touched
- The tests document current behaviour, including the odd rules the business relies on
- Laravel upgraded sequentially from 5.6 to 13, one major version per step, never skipping a release
- PHP moved from 7.1 to 8.4.27 along the way
- The whole rescue, tests and upgrades, done in 1 week
- How it fit in a week: characterization tests written with AI assistance and reviewed line by line, then automated upgrade steps checked against the suite
- The full suite green after every step, so each upgrade was provably safe to ship
- Policy certificates, invoices and claim files kept working through every upgrade
- Behaviour written down for the next developer: the tests, plus notes on the business rules they encode
What we built
Read the system as it is
We mapped the members, departments, policies, invoices and claims, and the permission rules between them, straight from the code and the database, because there was nothing else to read.
Characterization tests to 80%
Before changing anything, we wrote tests that pin down what the app does today: premium and invoice calculations, policy certificate downloads, claim uploads, age rules and department permissions. Where the behaviour looked wrong, we recorded it and asked, rather than fixing it silently.
One major version at a time
Laravel was bumped sequentially from 5.6 to 13, one release per step, and PHP from 7.1 to 8.4, with deprecated APIs, packages and config migrated at each stage. Nothing moved forward until every test passed.
Safe for the next team
The client now has a test suite that runs in minutes, Laravel 13 on PHP 8.4, and documentation of the business rules, so the next change is not a guess.
- PDF policy certificates
- Excel exports
- Email notifications
- Intranet deployment
- Laravel 5.6 → 13
- PHP 7.1 → 8.4.27
- PHPUnit
- wkhtmltopdf
- MySQL
Client name withheld: the app runs on the client's private intranet and holds members' health-policy data.
Stuck on an old Laravel version with no tests?
Start with the 10-day audit. It maps your upgrade path version by version, needs only read-only access, and 100% of the fee is credited to the rescue.