WP-Tests-Strapon

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

1. Make sure you have version 9 or 10 of PHPUnit installed as a development dependency for your project.
2. 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

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