Testing Framework

This document describes the testing infrastructure for the Auth0 WordPress plugin, including the Pest testing framework configuration, available test execution modes, coverage generation, and test organization. For information about other code quality tools that complement the testing framework, see Code Quality Tools.

Overview

The plugin uses Pest as its testing framework, a modern PHP testing framework built on top of PHPUnit. Pest provides an expressive syntax and is configured through phpunit.xml.dist and Composer scripts. The test suite is organized under the tests/ directory and focuses on unit testing the plugin's core functionality.

Sources: composer.json42-58 composer.json66-69 phpunit.xml.dist1-26

Test Organization

The test suite follows a structured organization based on test type:

Test Suite Structure

Component	Location	Purpose
Unit Tests	tests/Unit/	Unit tests for core plugin classes
Test Configuration	phpunit.xml.dist	PHPUnit/Pest configuration
Test Namespace	Auth0\Tests\	PSR-4 autoload namespace for tests

The test suite is defined in phpunit.xml.dist with a single unit test suite that includes all test files in the tests/Unit directory.

Sources: composer.json66-69 phpunit.xml.dist9-13

Test Configuration

The Pest framework is configured through phpunit.xml.dist, which defines test suites, coverage settings, environment variables, and source code inclusion/exclusion rules.

PHPUnit XML Configuration

Configuration Elements

Element	Configuration	Purpose
Test Suite	<testsuite name="unit">	Defines the unit test suite
Test Directory	<directory>tests/Unit</directory>	Specifies test file location
Coverage Reports	clover.xml, cobertura.xml	Output formats for coverage data
Source Include	<directory suffix=".php">./src/</directory>	Source code to analyze for coverage
Source Exclude	src/Events/, src/Exceptions/	Directories excluded from coverage
Environment	CACHE_DRIVER=array	Test environment configuration

Sources: phpunit.xml.dist1-26

Coverage Configuration

The plugin generates two types of coverage reports:

1. Clover Format: XML format for integration with CI/CD tools, output to coverage/clover.xml
2. Cobertura Format: XML format compatible with various coverage visualization tools, output to coverage/cobertura.xml

Coverage analysis includes all PHP files in src/ except for the Events/ and Exceptions/ directories, which are excluded because they primarily contain event classes and exception definitions that don't require unit testing.

Sources: phpunit.xml.dist3-8 phpunit.xml.dist17-25

Test Execution Modes

The plugin provides multiple Composer scripts for running tests with different configurations:

Standard Test Run

Executes tests with the following flags:

• --order-by random: Randomizes test execution order to detect order-dependent tests
• --fail-on-risky: Treats risky tests (e.g., tests without assertions) as failures
• --parallel: Runs tests in parallel for faster execution
• --no-progress: Suppresses progress indicators for cleaner output

Sources: composer.json99

Coverage Generation

Generates code coverage reports in both Clover and Cobertura formats. Uses the same execution flags as the standard run but adds the --coverage flag to enable coverage analysis. The coverage reports are written to the coverage/ directory as specified in phpunit.xml.dist.

Sources: composer.json100 phpunit.xml.dist3-8

Debug Mode

Executes tests with verbose logging for troubleshooting:

• --log-events-verbose-text pest.log: Writes detailed event logs to pest.log
• --display-errors: Shows detailed error information
• --fail-on-risky: Treats risky tests as failures
• --no-progress: Suppresses progress indicators

This mode is useful when investigating test failures or understanding test execution flow.

Sources: composer.json101

Performance Profiling

Profiles test execution to identify slow tests. The --profile flag reports execution time for each test, helping developers optimize test performance.

Sources: composer.json102

Test Execution Workflow

The following diagram illustrates how the test execution system integrates with the broader development workflow:

Sources: composer.json97-116 phpunit.xml.dist1-26

Testing Dependencies

The plugin includes several testing-related dependencies managed through Composer:

Dependency	Version	Purpose
pestphp/pest	^2	Primary testing framework
mockery/mockery	^1	Mocking library for isolating dependencies
psr-mock/http	^1	HTTP client mocking for PSR-18
buggregator/trap	^1	Debug and inspection tool
nyholm/psr7	^1	PSR-7 HTTP message implementation for testing
symfony/cache	^6	Cache implementation for testing

These dependencies are installed only in development environments (via require-dev) and are not included in production builds.

Sources: composer.json42-58

Integration with Quality Assurance

The test framework is part of a larger quality assurance system. The composer test command runs the complete test suite including Pest tests alongside other quality tools:

The composite test command ensures that code passes both functional tests (Pest) and static analysis checks (PHPStan, Psalm, Rector, PHP-CS-Fixer) before being considered ready for deployment. See Code Quality Tools for details on the static analysis components.

Sources: composer.json110-116

Test Environment Configuration

The phpunit.xml.dist configuration sets environment variables for test execution:

Variable	Value	Purpose
CACHE_DRIVER	array	Uses in-memory array cache for testing instead of filesystem or external cache

This configuration ensures tests run in an isolated environment without external dependencies. The array cache driver provides fast, ephemeral caching that resets between test runs.

Sources: phpunit.xml.dist14-16

Running Tests

To run the test suite during development:

Basic test execution:

Generate coverage reports:

Debug failing tests:

Profile test performance:

Run all quality checks (including tests):

The test framework automatically discovers and executes all test files in the tests/Unit/ directory that follow the Pest naming convention.

Sources: composer.json97-116