sebkay / touchstone

A tool for making the writing of tests in WordPress plugins and themes easier.

Touchstone

A modern wrapper around the official WordPress testsuite. It can be used to run both Unit and Integration tests.

---

Installation

Run the following command to install Touchstone in your project:

composer require sebkay/touchstone --dev

---

Usage

1.) Setup

Running the setup process downloads and installs both WordPress and the official WordPress test files in your temp directory.

# Options
./vendor/bin/touchstone setup --db-host=[HOST] --db-socket=[SOCKET PATH] --db-name=[DATABASE NAME] --db-user=[DATABASE USERNAME] --db-pass=[DATABASE PASSWORD] skip-db-creation

Regular Connection

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

via a Socket

./vendor/bin/touchstone setup --db-host=127.0.0.1:8889 --db-socket="/path/to/mysqld.sock" --db-name=touchstone_tests --db-user=root --db-pass=root

2.) Creating Tests

All your tests will need to be in the following structure from the root of your project:

tests/
    Unit/
        ExampleUnitTest.php
    Integration/
        ExampleIntegrationTest.php

All your Unit tests will need to extend the WPTS\Tests\UnitTest class and all your integrationt tests will need to extend the WPTS\Tests\IntegrationTest class.

Here's an example Unit test:

<?php

namespace WPTS\Tests\Unit;

class ExampleUnitTest extends UnitTest
{
    public function test_it_works()
    {
        $this->assertTrue(true);
    }
}

Here's an example Integration test:

<?php

namespace WPTS\Tests\Integration;

class ExampleIntegrationTest extends IntegrationTest
{
    public function test_post_title_was_added()
    {
        $post_id = $this->factory()->post->create([
            'post_title' => 'Example post title',
        ]);

        $post = \get_post($post_id);

        $this->assertSame('Example post title', $post->post_title);
    }
}

3.) Running Tests

You can run either all of your tests or a single testsuite with the following commands:

# Run all tests
./vendor/bin/touchstone test

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

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

4.) Configuration

You can configure certain things by creating a config.touchstone.php file in the root of your project.

Directories For Tests

Here's how to set the directories for where your tests are located:

<?php
# config.touchstone.php

return [
    'directories' => [
        'all'         => 'tests',
        'unit'        => 'tests/Unit',
        'integration' => 'tests/Integration',
    ],
];

WordPress Plugins

Here's how to load plugins which are loaded before each test.

This means for a plugin like ACF (Advanced Custom Fields) you can use functions like get_field() in your code and it won't break your tests.

Important: You will need to provide the plugin files. I recommend putting them all in bin/plugins/ in your theme/plugin and the adding that path to your .gitignore.

<?php
# config.touchstone.php

return [
    'plugins' => [
        [
            'name' => 'Advanced Custom Fields',
            'file' => dirname(__FILE__) . '/bin/plugins/advanced-custom-fields-pro/acf.php',
        ],
    ],
];

# Directories
bin/plugins

WordPress Theme

Here's how to load a theme which is active for each test.

<?php
# config.touchstone.php

return [
    'theme' => [
        'root' => dirname(__FILE__) . '/../../themes/twentytwentyone',
    ],
];

---

Composer Scripts

You can create Composer scripts so you don't need to memorise the above commands.

To do so add the following to your composer.json file:

...
    "scripts": {
        "touchstone:setup": "./vendor/bin/touchstone setup --db-host=[HOST] --db-name=[DATABASE NAME] --db-user=[DATABASE USER] --db-pass=[DATABASE PASSWORD] --skip-db-creation=true",
        "touchstone:test": "./vendor/bin/touchstone test",
        "touchstone:unit": "./vendor/bin/touchstone test --type=unit",
        "touchstone:integration": "./vendor/bin/touchstone test --type=integration"
    }
...

Then you can run the following from the command line:

# Run setup
composer touchstone:setup

# Run all tests
composer touchstone:test

# Run Unit tests
composer touchstone:unit

# Run Integration tests
composer touchstone:integration

---

Troubleshooting

Tests Won't Run

If you ever have problems running your tests, run the setup command. It's more than likely you've restarted your machine since the last time you ran the tests which deletes the WordPress test files. Re-running the setup process will usually fix the problem.

Why Does This Exist?

The official way of running the WordPress testsuite is horribly complicated and incredibly prone to user error.

Touchstone fixes both of those issues by making the process of creating and running tests easy.

touchstone's Issues

Be able to connect to the database host and verify connection works during setup

Allow custom plugins and theme to be loaded for integration tests

When testing plugins or themes with functionality that relies on something like Advanced Custom Fields, it's useful for the user to be able to specify MU (must use) plugins somehow.

This could also be a perfect time to introduce a Touchstone configuration file that could later be used for other types of configuration.

Example for config:

# touchstone.php
return [
    'plugins' => [
        [
            'name' => 'Advanced Custom Fields',
            'file' => dirname(__FILE__) . '/bin/plugins/advanced-custom-fields-pro/acf.php',
        ],
    ],
    'theme' => [
        'root' => dirname(__FILE__) . '/../../themes/twentytwentyone',
    ],
];

The above could then be loaded by Touchstone in the WP bootstrap file to load MU plugins and register the theme as the active one.

Download and save to temp directory latest version of WordPress during setup

Be able to create OR skip creating the database during setup

Create class to handle running PHPUnit tests

Create new class structure for running Touchstone

Will be using Symfony Console to handle the CMD parts.

Configure settings in WordPress test files (wp-tests-config.php)

Download and save latest version of WordPress test files to temp directory during setup

Add support for connecting via unix socket

Will need to add an option to the Setup command, something like --db-socket.

All need to add unix_socket= to the database string here somewhere:

touchstone/src/Console/Commands/Setup.php

Lines 155 to 170 in 1ab5858

	protected function connectToHost(InputInterface $input, OutputInterface &$output): void
	{
	$output->writeln(\WPTS\CMD_ICONS['loading'] . ' Testing connection...');
	$db_string = "mysql:host={$this->db_creds['host']};charset=UTF8";
	if ($input->getOption('skip-db-creation')) {
	$db_string .= ";dbname={$this->db_creds['name']}";
	}
	try {
	$db_connection = new \PDO(
	$db_string,
	$this->db_creds['user'],
	$this->db_creds['pass']
	);