{"id":14955142,"url":"https://github.com/sebkay/touchstone","last_synced_at":"2025-08-07T05:14:42.036Z","repository":{"id":37589599,"uuid":"377270365","full_name":"SebKay/touchstone","owner":"SebKay","description":"A tool for making the writing of tests in WordPress plugins and themes easier.","archived":false,"fork":false,"pushed_at":"2024-02-29T13:34:53.000Z","size":25171,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"4.x","last_synced_at":"2025-07-10T15:48:42.187Z","etag":null,"topics":["php","wordpress","wordpress-boilerplate","wordpress-development","wp-cli"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SebKay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-15T19:16:21.000Z","updated_at":"2025-06-05T13:20:58.000Z","dependencies_parsed_at":"2025-02-10T05:30:28.115Z","dependency_job_id":null,"html_url":"https://github.com/SebKay/touchstone","commit_stats":{"total_commits":96,"total_committers":4,"mean_commits":24.0,"dds":0.09375,"last_synced_commit":"c18e8387eeed50694360d50edb25e854a2b7329e"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/SebKay/touchstone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebKay%2Ftouchstone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebKay%2Ftouchstone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebKay%2Ftouchstone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebKay%2Ftouchstone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SebKay","download_url":"https://codeload.github.com/SebKay/touchstone/tar.gz/refs/heads/4.x","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SebKay%2Ftouchstone/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269201296,"owners_count":24377460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","wordpress","wordpress-boilerplate","wordpress-development","wp-cli"],"created_at":"2024-09-24T13:10:34.727Z","updated_at":"2025-08-07T05:14:41.989Z","avatar_url":"https://github.com/SebKay.png","language":"PHP","readme":"# Touchstone\n\n[![PHP](https://github.com/SebKay/touchstone/actions/workflows/php.yml/badge.svg)](https://github.com/SebKay/touchstone/actions/workflows/php.yml)\n\nA modern wrapper around the [official WordPress testsuite](https://make.wordpress.org/cli/handbook/misc/plugin-unit-tests/). It can be used to run both Unit and Integration tests.\n\n---\n\n## Installation\n\nRun the following command to install Touchstone in your project:\n\n```shell\ncomposer require sebkay/touchstone --dev\n```\n\n---\n\n## Usage\n\n### 1.) Setup\n\nRunning the setup process downloads and installs both WordPress and the official WordPress test files in your temp directory.\n\n```shell\n# Options\n./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\n```\n\n#### Regular Connection\n\n```shell\n# Example\n./vendor/bin/touchstone setup --db-host=127.0.0.1:8889 --db-name=touchstone_tests --db-user=root --db-pass=root\n```\n\n#### via a Socket\n\n```shell\n./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\n```\n\n### 2.) Creating Tests\n\nAll your tests will need to be in the following structure from the root of your project:\n\n```shell\ntests/\n    Unit/\n        ExampleUnitTest.php\n    Integration/\n        ExampleIntegrationTest.php\n```\n\nAll 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.\n\nHere's an example Unit test:\n\n```php\n\u003c?php\n\nnamespace WPTS\\Tests\\Unit;\n\nclass ExampleUnitTest extends UnitTest\n{\n    public function test_it_works()\n    {\n        $this-\u003eassertTrue(true);\n    }\n}\n```\n\nHere's an example Integration test:\n\n```php\n\u003c?php\n\nnamespace WPTS\\Tests\\Integration;\n\nclass ExampleIntegrationTest extends IntegrationTest\n{\n    public function test_post_title_was_added()\n    {\n        $post_id = $this-\u003efactory()-\u003epost-\u003ecreate([\n            'post_title' =\u003e 'Example post title',\n        ]);\n\n        $post = \\get_post($post_id);\n\n        $this-\u003eassertSame('Example post title', $post-\u003epost_title);\n    }\n}\n```\n\n### 3.) Running Tests\n\nYou can run either all of your tests or a single testsuite with the following commands:\n\n```shell\n# Run all tests\n./vendor/bin/touchstone test\n\n# Run Unit tests\n./vendor/bin/touchstone test --type=unit\n\n# Run Integration tests\n./vendor/bin/touchstone test --type=integration\n```\n\n### 4.) Configuration\n\nYou can configure certain things by creating a `config.touchstone.php` file in the root of your project.\n\n#### Directories For Tests\n\nHere's how to set the directories for where your tests are located:\n\n```php\n\u003c?php\n# config.touchstone.php\n\nreturn [\n    'directories' =\u003e [\n        'all'         =\u003e 'tests',\n        'unit'        =\u003e 'tests/Unit',\n        'integration' =\u003e 'tests/Integration',\n    ],\n];\n```\n\n#### WordPress Plugins\n\nHere's how to load plugins which are loaded before each test.\n\nThis 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.\n\n**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`.\n\n```php\n\u003c?php\n# config.touchstone.php\n\nreturn [\n    'plugins' =\u003e [\n        [\n            'name' =\u003e 'Advanced Custom Fields',\n            'file' =\u003e dirname(__FILE__) . '/bin/plugins/advanced-custom-fields-pro/acf.php',\n        ],\n    ],\n];\n```\n\n```gitignore\n# Directories\nbin/plugins\n```\n\n#### WordPress Theme\n\nHere's how to load a theme which is active for each test.\n\n```php\n\u003c?php\n# config.touchstone.php\n\nreturn [\n    'theme' =\u003e [\n        'root' =\u003e dirname(__FILE__) . '/../../themes/twentytwentyone',\n    ],\n];\n```\n\n---\n\n## Composer Scripts\n\nYou can create Composer scripts so you don't need to memorise the above commands.\n\nTo do so add the following to your `composer.json` file:\n\n```json\n...\n    \"scripts\": {\n        \"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\",\n        \"touchstone:test\": \"./vendor/bin/touchstone test\",\n        \"touchstone:unit\": \"./vendor/bin/touchstone test --type=unit\",\n        \"touchstone:integration\": \"./vendor/bin/touchstone test --type=integration\"\n    }\n...\n```\n\nThen you can run the following from the command line:\n\n```shell\n# Run setup\ncomposer touchstone:setup\n\n# Run all tests\ncomposer touchstone:test\n\n# Run Unit tests\ncomposer touchstone:unit\n\n# Run Integration tests\ncomposer touchstone:integration\n```\n\n---\n\n## Troubleshooting\n\n### Tests Won't Run\n\nIf 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.\n\n### Why Does This Exist?\n\nThe official way of running the WordPress testsuite is horribly complicated and incredibly prone to user error.\n\nTouchstone fixes both of those issues by making the process of creating and running tests easy.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebkay%2Ftouchstone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebkay%2Ftouchstone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebkay%2Ftouchstone/lists"}