Tests ​

Unit and integration tests ​

For unit and integration tests, Forme uses the excellent Pest. Pest uses PHPUnit under the hood, but with less boilerplate and a much nicer syntax inspired by Jest. If you've done any js/ts development, you'll feel right at home.

Test server ​

Forme uses a wp-test directory with a full WordPress installation set up for integration and end to end tests, hooked up to an SQLite database, and with your plugin or theme installed via the magic of symlinks. You can use the codegen to set this up:

forme test setup

The admin user is admin and the password is password. You can start or stop a local server if you want to inspect it in the browser.

forme test server start
forme test server stop

It will be available to use on http://localhost:8000 While it's perfectly serviceable as a local development server, bear in mind that the database state won't persist between integration test runs, so you shouldn't rely on that aspect of it. If you need something more persistent, you should use Valet or ketch/docker instead.

One important caveat is that due to core WordPress's ancient codebase and lack of modern PHP best practises in the plugin ecosystem, testing can be quite the challenge, so there will be bugs and edge cases where things simply don't work quite as expected. You can usually work around them, but it's not always plain sailing. So you should consider this feature experimental.

Writing and running tests ​

You can write tests within the tests/pest directory under Unit and Integration as relevant.

We'll be writing up some documentation here in due course, but for now you should check out the examples in the theme and plugin boilerplates for a steer on how this works, and refer back to Pest's documentation for the syntax.

To run your tests you can use any of the following commands

forme test run
forme test # shorter alias
composer test # composer script version
./tools/pest #  if you need to add any arguments or flags, use this. all of the above run this under the hood anyway.

Swapping out SQLite for MySQL ​

SQLite doesn't play nice with some plugins, for example WooCommerce and WP Cron. For some projects you might need to swap out SQLite for MySQL.

This will be automated in due course, but for now you can do the following, assuming an existing SQLite based test installatino via forme test setup

1. Create a test database in your local mysql UI or cli
2. Delete wp-test/public/wp-content/db.php
3. Delete phinx.yml (it will be recreated)
4. Manually edit wp-test/public/wp-config.php, change the db credentials and add define('USE_MYSQL', true); under define('WP_ENV', 'testing'); You can also optionally delete or comment out the DB_DIR and DB_FILE lines.
5. run wp core install --url="http://localhost:8000" --title="Test Site" --admin_user="admin" --admin_password="password" --admin_email="test@example.com"
6. Activate any required plugins e.g. wp plugin activate advanced-custom-fields
7. Activate your project's theme or plugin
8. Try running your tests with composer test

End to end tests (Coming soon) ​

We currently use Cypress for end to end tests on all of our Forme projects.

We're still in the process of automating the setup and porting the functionality into the Forme framework. Some of the initial work is already in there if you look closely at recent versions, but as yet undocumented.

Watch this space!