Skip to content

TESTING.md

Latest commit

 

History

History
155 lines (92 loc) · 3.11 KB

TESTING.md

File metadata and controls

155 lines (92 loc) · 3.11 KB

DocumentCloud Plugin – Unit Testing Guide

This document outlines the steps required to run unit tests for the DocumentCloud WordPress plugin. The testing suite includes both PHP unit tests for server-side functionality and JavaScript unit tests for the Gutenberg block component.

💻 Software Requirements

To run the unit tests for this plugin, ensure you have the following software installed:

General

  • Git

  • Composer

  • Node.js

  • npm

For PHP Unit Tests

  • PHP

  • PHPUnit (matching your PHP version)

  • MySQL or MariaDB

  • Subversion (svn)

🧪 PHP Unit Testing Setup

The PHP unit tests use the WordPress PHPUnit Test Suite.

1. Install Dependencies

From the root directory of the plugin, run:

composer install

This will install all PHP dependencies, including PHPUnit and test configuration.

2. Setup WordPress Test Environment

The WordPress test suite is already included in the repository via the script at bin/install-wp-tests.sh.

Make the script executable:

chmod +x bin/install-wp-tests.sh

Run the script with appropriate parameters:

./bin/install-wp-tests.sh <db-name> <db-user> <db-pass> [db-host] [wp-version]

  • Replace <db-name>, <db-user>, <db-pass> with your local database credentials.

  • ⚠️ Note: Ensure that svn is installed on your system, as the script uses Subversion to fetch the WordPress core files.

3. Run the PHPUnit Tests

After successful setup:

phpunit

To run with code coverage output:

phpunit --coverage-text

📌 Ensure you are running this from the plugin root and have phpunit.xml.dist properly configured.

🧪 Running PHPUnit Tests Inside Docker

If you are using Docker for your development environment, follow these steps to run PHPUnit tests inside the Docker container:

1. Start the Docker Containers

docker compose up --build

2. Open Shell into the Testing Service

docker exec -it Testing bash

3. Install the WordPress Test Suite

./bin/install-wp-tests.sh test root password db latest

4. Run the PHPUnit Tests

./vendor/bin/phpunit

🧪 JavaScript Unit Testing Setup

The Gutenberg block of this plugin is tested using Jest and React Testing Library.

1. Navigate to the Blocks Directory

cd blocks/

2. Install JavaScript Dependencies

npm install

3. Run the JS Tests

npm run test

or

npx jest

4. Test Directory Structure

  • __tests__/ – Contains all Jest test files.

  • __mocks__/ – Includes mocks for WordPress-specific packages.

  • __snapshots__/ – Stores Jest snapshot tests, for the save component of the block.

⚠️ If you've made changes to how the save function renders content, delete existing snapshots to regenerate them:

rm -rf __snapshots__/