Testing Infrastructure

Purpose and Scope

This document describes the testing infrastructure for the BuddyPress VIP Go plugin, including test suite organization, execution strategies, and continuous integration configuration. The testing system employs a dual-strategy approach: unit tests with mocked WordPress functions and integration tests with full WordPress environments.

For information about local development environment setup, see Local Development Setup. For details on the CI/CD pipeline execution, see CI/CD Pipeline.

Testing Strategy Overview

The plugin implements two distinct testing approaches to ensure code quality and compatibility:

Test Type	Purpose	Dependencies	Execution Environment
Unit Tests	Fast, isolated tests of logic without WordPress	BrainMonkey, PHPUnit 9.6	PHP process only
Integration Tests	End-to-end tests with real WordPress installation	wp-env, WordPress core, PHPUnit 9.6	Docker containers

Both test types are executed against multiple WordPress versions (6.6 minimum, master bleeding-edge) and PHP versions (8.2, latest, 8.5) to ensure broad compatibility.

Sources: phpunit.xml.dist1-33 composer.json29-30

Test Suite Architecture

Diagram: Test Suite Architecture and Dependencies

The testing infrastructure uses a smart bootstrap detection system at tests/bootstrap.php10-28 that examines the PHPUNIT_TESTSUITE environment variable or command-line arguments to determine which bootstrap file to load. This allows unit and integration tests to coexist in the same repository with different initialization requirements.

Sources: tests/bootstrap.php1-29 phpunit.xml.dist14-21 composer.json52-54

PHPUnit Configuration

The phpunit.xml.dist1-33 file defines two distinct test suites:

Configuration Details

Setting	Value	Purpose
bootstrap	tests/bootstrap.php	Main entry point with suite detection logic
backupGlobals	false	Performance optimization
colors	true	Enhanced output readability
convertErrorsToExceptions	true	Treat PHP errors as test failures
beStrictAboutTestsThatDoNotTestAnything	true	Enforce test assertions
beStrictAboutOutputDuringTests	true	Detect unexpected output

The coverage configuration at phpunit.xml.dist23-32 includes all .php files except node_modules, tests, and vendor directories.

Sources: phpunit.xml.dist1-33

Unit Test Infrastructure

Unit tests leverage BrainMonkey to mock WordPress functions without requiring a WordPress installation, enabling fast, isolated testing.

Unit Test Bootstrap Process

Diagram: Unit Test Bootstrap Sequence

The unit test bootstrap at tests/Unit/bootstrap.php1-12 is minimal, loading only the Composer autoloader. This simplicity is intentional—unit tests should not depend on WordPress core.

Unit Test Base Class

The TestCase class at tests/Unit/TestCase.php1-17 extends Yoast\WPTestUtils\BrainMonkey\TestCase, providing:

• Automatic BrainMonkey setup/teardown for each test
• WordPress function mocking capabilities via Brain\Monkey\Functions\when()
• Filter/action hook mocking via Brain\Monkey\Actions\expectDone() and Brain\Monkey\Filters\expectApplied()

Sources: tests/Unit/bootstrap.php1-12 tests/Unit/TestCase.php1-17 composer.json30

Integration Test Infrastructure

Integration tests execute within a full WordPress environment provided by wp-env Docker containers, testing real plugin behavior with actual WordPress core functions.

Integration Test Bootstrap Process

Diagram: Integration Test Bootstrap Sequence

The integration bootstrap at tests/Integration/bootstrap.php1-49 performs critical setup:

1. Line 11: Loads Composer autoloader for test namespace
2. Line 14: Loads Yoast WP Test Utils integration functions
3. Line 17: Calls WPIntegration\get_path_to_wp_test_dir() to locate WordPress test library
4. Lines 28-34: Uses tests_add_filter() to load the plugin during muplugins_loaded hook, ensuring plugin loads before WordPress initializes
5. Line 40: Bootstraps WordPress test environment
6. Line 48: Registers mock object autoloader for PHP 8 compatibility

Integration Test Base Class

The TestCase class at tests/Integration/TestCase.php1-17 extends Yoast\WPTestUtils\WPIntegration\TestCase, which itself extends WordPress's WP_UnitTestCase. This provides:

• WordPress database fixture management
• Factory methods for creating users, posts, terms
• Automatic database transaction rollback between tests
• Access to all WordPress core functions

Example Integration Test

The tests/Integration/PluginTest.php1-25 demonstrates basic integration testing:

This test verifies the plugin's hook registration by calling the real WordPress has_action() function, which only works in a full WordPress environment.

Sources: tests/Integration/bootstrap.php1-49 tests/Integration/TestCase.php1-17 tests/Integration/PluginTest.php1-25 composer.json30

Test Execution Methods

Composer Script Execution

The composer.json44-67 file defines standardized test execution scripts:

Command	Purpose	Environment	Execution Path
composer test:unit	Run unit tests only	Local PHP process	phpunit --testsuite Unit
composer test:integration	Run integration tests (single-site)	wp-env Docker container	wp-env run tests-cli ./vendor/bin/phpunit --testsuite WP_Tests
composer test:integration-ms	Run integration tests (multisite)	wp-env Docker container with WP_MULTISITE=1	wp-env run tests-cli /bin/bash -c 'WP_MULTISITE=1 ./vendor/bin/phpunit --testsuite WP_Tests'
composer coverage	Generate HTML coverage report	Local PHP process	phpunit --coverage-html ./build/coverage-html
composer coverage-ci	Output coverage to stdout	CI environment	phpunit (relies on phpunit.xml config)

wp-env Execution Context

Integration tests execute inside the tests-cli container provided by wp-env. The commands use:

• wp-env run tests-cli to execute commands in the container
• --env-cwd=wp-content/plugins/buddypress-vip-go to set working directory to plugin location
• /bin/bash -c for multisite tests to set environment variables before PHPUnit execution

Sources: composer.json52-54

Continuous Integration Execution

Diagram: CI Integration Test Workflow

Test Matrix Configuration

The .github/workflows/integration.yml37-46 defines a fail-fast matrix:

The fail-fast: false setting ensures both matrix combinations complete even if one fails, providing complete compatibility visibility.

WordPress Version Selection

The workflow uses the WP_ENV_CORE environment variable at .github/workflows/integration.yml76 to specify which WordPress version wp-env should install:

This instructs wp-env to clone the WordPress repository at the specified branch (6.6 or master).

PHP Platform Requirements

The .github/workflows/integration.yml65 uses --ignore-platform-req=php+ when installing Composer dependencies:

This allows testing against PHP versions that may not match composer.json requirements (e.g., testing PHP 8.5 when only 8.2 is declared).

Concurrency Control

The workflow implements concurrency control at .github/workflows/integration.yml25-27:

This cancels any previous workflow runs for the same branch when new commits are pushed, optimizing CI resource usage.

Sources: .github/workflows/integration.yml1-83

Test Coverage Configuration

The coverage configuration at phpunit.xml.dist23-32 defines which files are analyzed:

Included Files

• All .php files in the root directory and subdirectories

Excluded Directories

• ./node_modules - JavaScript dependencies
• ./tests - Test files themselves
• ./vendor - PHP dependencies

The composer coverage command generates an HTML report in ./build/coverage-html, while composer coverage-ci outputs machine-readable format suitable for CI/CD integration with coverage analysis tools.

Sources: phpunit.xml.dist23-32 composer.json45-46

Test Dependencies and Requirements

Core Testing Dependencies

Package	Version	Purpose
phpunit/phpunit	^9.6	PHPUnit test framework
yoast/wp-test-utils	^1.2	WordPress integration utilities, BrainMonkey wrapper
@wordpress/env	npm global	Docker-based WordPress environment

WordPress Environment Requirements

Integration tests require:

• Docker and Docker Compose (for wp-env)
• Node.js and npm (to install @wordpress/env)
• At least 2GB available RAM for Docker containers
• Network access to download WordPress core

Execution Environment Variables

Variable	Used By	Purpose
WP_VERSION	Integration tests	Specifies WordPress version for wp-env
WP_MULTISITE	Multisite tests	Activates multisite configuration in WordPress
PHPUNIT_TESTSUITE	Bootstrap detection	Identifies which test suite is running
WP_ENV_CORE	wp-env	Specifies WordPress core repository and branch

Sources: composer.json25-30 .github/workflows/integration.yml34-36 tests/bootstrap.php11

Running Tests Locally

Prerequisites

1. Install Composer dependencies:

2. Install wp-env globally (for integration tests):

3. Start wp-env (for integration tests):

Execution Commands

Unit Tests (Fast, No WordPress Required):

Integration Tests Single-Site:

Integration Tests Multisite:

All Tests with Coverage:

The coverage report will be generated at ./build/coverage-html/index.html.

Sources: composer.json52-54

Test Organization Best Practices

Directory Structure

tests/
├── bootstrap.php # Suite detection router
├── Unit/
│ ├── bootstrap.php # Unit test bootstrap (minimal)
│ └── TestCase.php # Base class with BrainMonkey
├── Integration/
│ ├── bootstrap.php # Integration bootstrap (WP setup)
│ ├── TestCase.php # Base class with WPIntegrationTestCase
│ └── PluginTest.php # Example integration test

Naming Conventions

• Test classes: *Test.php (e.g., PluginTest.php)
• Test methods: test_* prefix (e.g., test_plugin_loaded)
• Bootstrap files: bootstrap.php in each suite directory
• Base classes: TestCase.php in each suite directory

When to Use Each Test Type

Use Unit Tests For:

• Testing pure functions without WordPress dependencies
• Testing class methods that can be mocked
• Fast feedback during development
• Testing error handling and edge cases

Use Integration Tests For:

• Testing WordPress hook registrations
• Testing database operations
• Testing interactions with BuddyPress/BuddyBoss
• Testing the complete plugin initialization sequence

Sources: tests/Integration/PluginTest.php15-24 tests/Unit/TestCase.php1-17 tests/Integration/TestCase.php1-17