System Test for Laravel

This package is abandoned and no longer maintained.

There is no drop-in replacement. What replaced it is a pattern rather than a package, described in The pattern that replaced it below.

The tagged releases remain installable. test:schedule was made redundant by Laravel's own schedule:list in Laravel 9, and the package supports no Laravel version that is still receiving security fixes.

This package provides a number of console commands to test various subsystems (email, logging, notifications, etc) of a Laravel system in production. It is primarily intended for troubleshooting issues on a newly deployed application or if you've moved to a new server - identifying permissions errors and such.

By Simon Hampel

The pattern that replaced it

Seven standalone commands that each print a paragraph turned out to be the wrong shape. What works better is a single app:validate command, and these are the parts of it worth copying.

Exercise the real thing. Run the binary, connect to the database, write the file, send the message. A check that reads configuration back and reports it is a different command — call it app:config — and conflating the two is what lets a system report itself healthy while being unable to do any of it.

One command, sectioned, not one command per subsystem. An operator troubleshooting a deployment wants one thing to run, and wants the whole report even when the first section fails.

Four outcomes, not two. ok, warn, fail, and skip. Skip is the one people leave out and then miss: a subsystem that is deliberately not configured is not a failure, and reporting it as one trains everybody to ignore the output. Warn is for what works now and will bite later — a log stack resolving to the null channel, a queue with no worker.

The exit code is the product. This package got that wrong: every command but one returns nothing after reporting an error, so a failed test:mail exits 0. Nothing can gate on that — not a deployment script, not cron, not a health check. Fail the command when a check fails.

A probe that cannot start is a failed check, not a crash. Wrap each one. The first probe throwing must not cost you the report from every probe after it, which is the run you most need when a machine has just been rebuilt.

Probes worth having, roughly in the order they earn their place: write a log record at every severity; send mail to a nominated address; round-trip a cache key (write, increment, read back, delete — a store that accepts writes and returns stale values passes a weaker test); write and then delete a file on each configured disk, which proves both permissions; run each external binary; list each remote; post to each outbound webhook.

Report the values that decide behaviour, and redact the ones that are credentials. A webhook URL is a credential — output like this gets pasted into support tickets.

For the rendering — check rows, sections, exit code, settings tables — see hampel/console-report, which is where the reusable half of this package ended up.

The commands themselves

Kept for anyone still running a tagged release. Install with composer require hampel/systemtest; the artisan commands below then become available.

Mail

Ensure that mail has been configured and then run the test:mail console command with a destination email address as the parameter.

artisan test:mail foo@example.com

Log

Run the test:log console command to write a series of logs covering all severities to the default log file.

The --channel option can be used to specify any other configured logging channel.

artisan test:log --channel=syslog

Filesystem

Run the test:file console command to list all files available on the default disk.

The --disk option can be used to specify any other configured disk (eg local or public).

artisan test:file --disk=public

Note that no files are written to the disk.

Cache

Run the test:cache console command to write test writing to and retrieving from the default cache store.

The --store option can be used to specify any other configured cache store.

artisan test:cache --store=array

The test will generate a random key, write it to the cache (provided the key doesn't already exist), increment the value, then retrieve and delete the key - checking that the returned value is as expected.

Schedule

Run the test:schedule console command to output details of scheduled commands to the console.

Upload

Run the test:upload <path> console command to upload the file at <path> to your default filesystem disk and report back on the time taken.

The --disk option can be used to specify any configured disk (eg local or s3).

artisan test:file /path/to/foo.jpg --disk=s3

Note that the file will be uploaded to the root of the disk and then deleted - so both write and delete permissions are required.

A large test file such as those used by the Linode Speedtest are good for testing upload speeds.

Notifications

Run the test:notification <channel> <destination> console command to send a notification to the selected channel.

Currently supported channels are mail and slack. The destination must also be specified, for mail that would be the email address to send to and for Slack it would be the inbound webhook URL.

For example:

artisan test:notification mail foo@example.com

artisan test:notification slack https://hooks.slack.com/services/...

Be sure to check your inbox or Slack channel for a test notification message.