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.
Here's the command needed to run the setup process:
# Command
./vendor/bin/touchstone setup --db-host=[HOST] --db-name=[DATABASE NAME] --db-user=[DATABASE USER] --db-pass=[DATABASE PASSWORD] --skip-db-creation=[FALSE]
# Example
./vendor/bin/touchstone setup --db-host=127.0.0.1:8889 --db-name=touchstone_tests --db-user=root --db-pass=root --skip-db-creation=true
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:
namespace WPTS\Tests\Unit;
class ExampleUnitTest extends UnitTest
{
public function test_it_works()
{
$this->assertTrue(true);
}
}
Here's an example Integration test:
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
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=[FALSE]",
"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.
344 Jan 1, 2023
91 Dec 26, 2022
3 Nov 15, 2021
185 Nov 16, 2022
3 Dec 7, 2022
1 Oct 12, 2022
6 Nov 30, 2022
11 Sep 27, 2022
5 Oct 27, 2022
3.3k Jan 5, 2023
1 Oct 19, 2021
414 Nov 28, 2022
24 Nov 3, 2022
497 Dec 10, 2022
112 Nov 10, 2022
1 Jan 4, 2022
9 Oct 10, 2022
122 Oct 24, 2022
2 Sep 7, 2022