Touchstone – WordPress Unit & Integration Tests

WordPress 02 February 2022 3 minute read

The official way of running the WordPress testsuite is horribly complicated and prone to user error. Touchstone fixes both of those issues by making the process of creating and running tests easy.

Touchstone WordPress tests on GitHub

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= --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):


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!