Testing & Debugging - dotherightthing/wpdtrt-plugin-boilerplate GitHub Wiki

Summary

DTRT WordPress Plugin Boilerplate supports common & best practice approaches to debugging and testing.

Status

• Stable @ 1.5.0

---

Usage

Testing

A) Demo shortcode

The demo shortcode can also be useful in checking that different shortcode arguments and combinations generate the correct output.

---

B) Manual testing

Testing the plugin in a dedicated WordPress install prevents other plugins from contributing their own bugs.

---

C) WordPress Unit tests

Unit tests may be authored in ./tests/test-pluginname.php.

Authoring WordPress Unit tests

Useful links:

• DTRT - PHP Unit Testing, revisited
• https://phpunit.readthedocs.io/en/7.1/configuration.html
• http://richardsweeney.com/testing-integrations/
• Collection of notes on WP_UnitTestCase
• https://core.trac.wordpress.org/browser/trunk/tests/phpunit/includes/factory.php
• https://core.trac.wordpress.org/browser/trunk/tests/phpunit/includes/factory/
• How to Use WP_UnitTestCase go_to() to Simulate Current Page
• https://codesymphony.co/writing-wordpress-plugin-unit-tests/#object-factories
• https://miya0001.github.io/wp-unit-docs/
• https://codesymphony.co/creating-your-own-wordpress-unit-test-factories/
• What's the difference between a mock & stub?

Automated WordPress testing (local)

WP_UnitTestCase tests create a dedicated WordPress environment at runtime.

MAMP Settings

Window > Main Window > MySQL > Allow network access to MySQL: only from this Mac

You may test/debug this with:

mysqladmin create database_name --user=theuser '--password=thepassword' --host=localhost --protocol=tcp

Environmental variables (1.4.25)

Add your local MySQL credentials to your bash profile, to avoid storing multiple copies of sensitive information.

$ sudo nano ~/.bash_profile
$ export WPUNIT_DB_USER="foo"
$ export WPUNIT_DB_PASS="bar"
$ export WPUNIT_DB_HOST="127.0.0.1"

Running tests

Tests can be run as follows. Test results are output to the Terminal.

// Setup (if not run already)
composer install
yarn install 
yarn run build

// Run tests
yarn run test

If you are having problems installing the WordPress Test Suite, please read PHP Unit Testing, revisited for setup gotchas and solutions.

Automated WordPress testing (CI server)

When code is pushed to the GitHub repository, any WordPress unit tests are automatically run by the Travis CI (Continious Integration) server.

If any of these tests fail, the build|passing badge on the GitHub project page will change to read build|failing. Click the badge to view the Travis build log to better understand which test has failed.

Tenon Accessibility testing via WordPress

TODO: Code needs to be merged into boilerplate and documented here.

• DTRT WordPress Plugin Boilerplate - Add Tenon WCAG linting (#121)
• DTRT Gallery 1.7.15 - Shortcode test

WordPress Debugging

A) Debug helper

PHP can be debugged using the bundled DTRT Debug.

Setup

Add this code to your_wordpress_folder/wp-config.php:

define('WP_DEBUG', true);

if ( WP_DEBUG ) {
  define('WP_DEBUG_LOG', true);
  define('WP_DEBUG_DISPLAY', false);
  @ini_set('display_errors', 0);
}

Usage

<?php
...
global $debug;
$debug->log( $STRING_OR_ARRAY );
...

?>

Other debugging functions are available.

Viewing debug messages

Debug messages are output to your_wordpress_folder/wp-content/debug.log

---

D) Cypress.io Front End Unit tests

See: Testing & Debugging: Cypress.io

Documentation

• JavaScript (JSDoc, see jsdoc.json)
• PHP (PHP Documentor, see phpdoc.dist.xml)