Touchstone – WordPress Unit & Integration Tests

The Problem

I've been building WordPress themes and plugins since 2009. 13 years is long time to be building on top of a framework that has no real ideology when it comes to testing.

In 2019 I started to look at ways of writing unit and integration for my WordPress theme and plugins. To cut a long story short, the process was more pain inducing than I could've ever realised.

What makes writing tests for WordPress plugins and themes so difficult?

1. There's so little documentation, it's almost non-existent.
2. Getting set up is near impossible without diving deep into how the test runner works (it's a dirty bash script).
3. The documentation that does exist is outdated, meaning the steps to follow usually don't work.
4. You have to be a seasoned tester to get up and running. This is due to a mix of bad documentation and the way testing is implemented.
5. WordPress is, at it's core, an application. So any tests you write need to have a version of WordPress running. So all unit tests are really integration tests.

The Solution

In 2021, nearly two years after first attempting to write tests for anything in WordPress, I knew the solution: To build my own test runner that sits on top of PHPUnit and WordPress.

Touchstone is my solution to the many WordPress testing issues I've faced myself.

It provides a simple API which fixes the biggest issue of all, getting set up. To do all the setup steps required to run your tests, simply run:

./vendor/bin/touchstone setup --db-host=127.0.0.1:8889 --db-name=touchstone_tests --db-user=root --db-pass=root

Provide it with the relevant info for your local database and it'll do the rest.

You can also pass it a unix socket (helpful if you use something like Local):

--db-socket=/path/to/mysql.sock

To run your tests, you run:

# All tests
./vendor/bin/touchstone test

# Unit tests
./vendor/bin/touchstone test --type=unit

# Integration tests
./vendor/bin/touchstone test --type=integration

Give it a Try!

If you like the sound of no longer fighting WordPress for hours on end just to get the testing environment set up, then please give Touchstone a go.

If you've tried it, please let me know what you think!