Strap the WordPress PHPUnit tests library onto your WordPress plugin or theme with this handy Composer package.
This PHP Composer package facilitates the configuration and installation of a WordPress test environment so that WordPress' functionality can be used in your PHPUnit test suite.
In essence, it has the same purpose as the install-wp-tests.sh
shell script installed by the WP-CLI scaffolder, but takes a more streamlined approach:
- It comes as a PHP Composer package, simplifying updates and maintainance, with no extra files in your own codebase
- Is 100% programmed in PHP, so it does not require skills beyond that to contribute to the project
- Has the same dependencies as one can expect from any WordPress development environment (the
cURL
andZipArchive
PHP modules) - Does not depend on ancient technology that nobody should use anymore, such as Subversion
- The test environments are downloaded and configured automatically using information from your PHPUnit configuration file and environment variables
- No need to re-run a script to install a development environment with the same parameters after every time you restart your computer or development environment
WP-Tests-Strapon integrates with PHPUnit and acts as a bootstrap layer between it and your WordPress plugin's test suite. Simply run ./vendor/bin/phpunit
as you would generally do after following the installation instructions below.
For more information on PHPUnit itself and how to write tests, you should read their documentation.
- Make sure you have version 9 or 10 of PHPUnit installed as a development dependency for your project.
- Install the Composer package using
composer require --dev aldavigdis/wp-tests-strapon
.
Finally, Open up your PHPUnit configuration file (phpunit.xml
or phpunit.xml.dist
) and set the bootstrap
attribute of the root <phpunit>
element to vendor/aldavigdis/wp-tests-strapon/bootstrap.php
.
Alternatively, you can include or require vendor/aldavigdis/wp-tests-strapon/bootstrap.php
in your own PHPUnit bootstrap file.
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
xmlns:xsi="http:https://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.0/phpunit.xsd"
cacheResult="false"
bootstrap="vendor/aldavigdis/wp-tests-strapon/bootstrap.php"
>
<php>
<env name="DB_USER" value="test_user" />
<env name="DB_NAME" value="myawesome_plugin_test" />
</php>
<testsuites>
<testsuite name="Project Test Suite">
<directory>tests</directory>
</testsuite>
</testsuites>
</phpunit>
You can set those in your phpunit.xml
file, in your terminal session or in your test and production environments.
WP_TESTS_CONFIG_FILE_PATH
(constant): The location of your test environment's config file. Defaults to/tmp/wp-tests-strapon/config.php
on Linux/Unix/macOS.WP_VERSION
(environment variable): The PHP version to test against. Defaults tomaster
.
The following constants will be set in your WordPress test configuration file:
WP_DEFAULT_THEME
WP_TESTS_MULTISITE
WP_DEBUG
TABLE_PREFIX
DB_NAME
DB_USER
DB_PASSWORD
DB_HOST
WP_TESTS_DOMAIN
WP_TESTS_EMAIL
WP_TESTS_TITLE
WP_PHP_BINARY
WPLANG
The default values can be overridden when the file is generated by setting environment variables of the same name. You can do it using your PHPUnit configuration file, the PHPUnit runtime parameters, globally in your terminal or in your CI environment.
- Test the database connection when the config file is initialised
- Create the database if it does not exsist
- Improve documentation
- Add more tests
- Add more glitter
- Test on a Mac
- Get Windows support sorted out (both CMD and PowerShell)
Q: Why did you choose the AGPL license as opposed to a less restrictive one?
A: The AGPL makes sure that those who are using my software without paying contribute back if they modify it. If you would like a different licensing agreement for a fee, then that can be arranged.
Q: What's with the emoji everywhere?
A: What's with you being so boring and dull?
Copyright (c) 2024 Alda Vigdís Skarphéðinsdóttir
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.
For questions regarding the license or requests for alternative license arrangements, please contact the author at [email protected].