README

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 and ZipArchive 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

Usage

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.

Installation

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.

Example PHPUnit configuration file

<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    xmlns:xsi="http://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>

Environment variables and constants

You can set those in your phpunit.xml file, in your terminal session or in your test and production environments.

PHPUnit Bootstrap

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 to master.

Config File Constants

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.

The Todo List

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)

FAQ

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?

License

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 aldavigdis@aldavigdis.is.

aldavigdis / wp-tests-strapon

Maintainers

Details