Skip to content


Leaf is built with testing in mind. However, since you might need to quickly setup a project for a showcase or non-mainstream reason, we don't add any test library to the default Leaf installation, but can be added by simply installing our Alchemy module.


Before you continue, keep in mind that Alchemy is only a test runner, not a test framework. Alchemy runs tests using Pest/PHPUnit (Pest by default).

Why Test?

Automated tests help you and your team build complex Leaf apps quickly and confidently by preventing regressions and encouraging you to break apart your application into testable functions, modules, classes, and components. As with any app, your new Leaf app can break in many ways, and it's important that you can catch these issues and fix them before releasing.

When to Test

Start testing early! We recommend you begin writing tests as soon as you can. The longer you wait to add tests to your application, the more dependencies your application will have, and the harder it will be to start.

Adding tests to a new project

From Leaf CLI v2.3, you will be asked if you wish to add tests to your application. From there, Alchemy and default tests are setup for you. You can update and run these tests using the Leaf CLI:

leaf test

Or directly from Alchemy:

./vendor/bin/alchemy run

Adding tests to an existing project

If you've already setup a Leaf project, you can add tests by simply installing the Alchemy module. You can do this with the Leaf CLI:

leaf install alchemy

Or with composer

composer require leafs/alchemy

Your first test

After installing alchemy, you can quickly generate a sample test with a single command:

./vendor/bin/alchemy setup

If you're using PHPUnit, you'll have to add a --phpunit option to the setup command:

./vendor/bin/alchemy setup --phpunit

After this, you can add the specific tests you need in your app. You can then execute these tests using the Leaf CLI:

leaf test

Or directly from Alchemy:

./vendor/bin/alchemy run

You should see something like this:

  • PestPHP

  • PHPUnit


As mentioned before, Alchemy simply runs your tests for you. It allows you to run tests without having to do a ton of config first or even write a phpunit.xml. All config is handled by Alchemy itself. However, if you want to have control over the phpunit.xml file, you can export Alchemy's default config to create a phpunit.xml file. You can do this with:

./vendor/bin/alchemy config:export

After running the command listed above, you'll have access to a phpunit.xml file. Any configuration you need for either Pest or PHPUnit can be done in there.

If you want to totally switch from alchemy to pest or phpunit, you can eject your tests.

./vendor/bin/alchemy config:eject

This creates a phpunit.xml file and completely removes everything alchemy related.

Testing has loaded