Testing with Pest

This document covers the Pest testing framework integration in Maho, including the test database matrix (MySQL, MariaDB, PostgreSQL, SQLite), integration and API testing patterns, and automated quality assurance workflows.

Purpose and Scope

Maho uses the Pest PHP testing framework to validate functionality across multiple database engines and PHP versions. The testing system provides:

• Multi-database validation: Tests run against MySQL (8.4, latest), MariaDB (10.11, latest), PostgreSQL (14, latest), and SQLite.
• API Testing Framework: A JSON-RPC client framework for testing service-layer logic, particularly for modern modules like the Blog module.
• Integration Testing: Full application lifecycle tests including EAV models, configuration, and indexers.
• Automated CI/CD integration: GitHub Actions workflows with matrix strategies for comprehensive coverage.
• Isolated test environments: Database services run in Docker containers within the CI environment.

Pest Framework Overview

Pest is a modern PHP testing framework that provides an expressive syntax built on top of PHPUnit. Maho integrates Pest as a development dependency and executes tests through the vendor/bin/pest binary.

Test Execution Command

The --display-errors and --display-warnings flags ensure all PHP errors and warnings are displayed during test execution, making debugging easier.

Sources: .github/workflows/pest.yml127 .github/workflows/pest.yml180

Test Database Matrix

Maho tests run against a variety of database engines to ensure compatibility across different deployment scenarios.

Database Engine Support in Code

The codebase implements specific adapters for each supported engine, utilizing Doctrine DBAL for abstraction:

• MySQL/MariaDB: Handled by Maho\Db\Adapter\Pdo\Mysql
• PostgreSQL: Handled by Maho\Db\Adapter\Pdo\Pgsql
• SQLite: Handled by Maho\Db\Adapter\Pdo\Sqlite

CI Matrix Strategy

The GitHub Actions configuration defines a matrix to test various database versions.

Sources: .github/workflows/pest.yml18-56 .github/workflows/pest.yml129-130

Service Configuration and Health Checks

Database Name	Docker Image	Engine Type	Health Check Command
mysql-8.4	mysql:8.4	mysql	mysqladmin ping
mysql-latest	mysql:latest	mysql	mysqladmin ping
mariadb-10.11	mariadb:10.11	mysql	healthcheck.sh --connect --innodb_initialized
pgsql-14	postgres:14	pgsql	pg_isready

Sources: .github/workflows/pest.yml20-55

Integration and API Testing

Maho includes specialized test patterns for integration and API validation, particularly focusing on the JSON-RPC interface.

JSON-RPC API Testing

Maho provides a robust framework for testing its API endpoints. This is heavily utilized by the Maho_Blog module to verify post and category management.

• MahoApiTestCase: The base class for API-focused tests, providing setup for the JSON-RPC environment.
• JsonRpcClient: A client utility used to dispatch requests to the Maho API and validate JSON-RPC responses.
• BlogPostApiTest Pattern: A standard pattern for testing CRUD operations and visibility logic via the API.

Local Test Runner

For local development, the pest-with-test-db.php script facilitates running tests with a dedicated test database. This script automates the creation of a temporary database environment, ensuring the local development database remains untouched and providing a consistent state for test execution.

Test Organization

Tests are organized into logical suites based on their target area:

• Unit Tests: Found in tests/Backend/Unit/, such as ForwardDispatchTest.php or RouteResolutionTest.php.
• Integration Tests: Validate the interaction between multiple components, such as routing and controller dispatching.
• API Tests: Validate JSON-RPC endpoints, typically found within module-specific test directories.

Sources: tests/Backend/Unit/Maho/Routing/ForwardDispatchTest.php1 tests/Backend/Unit/Maho/Routing/RouteResolutionTest.php1

GitHub Actions Workflow

Workflow Triggers

The Pest test workflow triggers on:

• push to main branch.
• pull_request to any branch.
• workflow_call and workflow_dispatch.

Sources: .github/workflows/pest.yml3-9

Workflow Architecture

The following diagram illustrates the lifecycle of a test run in the CI environment.

Sources: .github/workflows/pest.yml12-181

Test Setup Process

Each test matrix run performs a complete Maho installation with sample data before executing tests.

Installation Parameters

The ./maho install command is used to bootstrap the environment. Key flags include:

• --db_engine: Specifies mysql, pgsql, or sqlite .github/workflows/pest.yml112
• --sample_data 1: Triggers the installation of sample data .github/workflows/pest.yml122
• --admin_password: Sets the administrative credential used for backend tests .github/workflows/pest.yml121

Post-Installation Preparation

Before Pest runs, the environment is prepared via:

1. Reindexing: ./maho index:reindex:all .github/workflows/pest.yml123
2. Cache Clearing: ./maho cache:flush .github/workflows/pest.yml124

Sources: .github/workflows/pest.yml101-125

Running Tests Locally

To run Pest tests locally, developers should follow the same sequence used in CI:

1. Dependency Installation: composer install .github/workflows/pest.yml96
2. Database Setup: Ensure a local instance of MySQL, PostgreSQL, or a file for SQLite is available.
3. Maho Installation:
   .github/workflows/pest.yml159-175
4. Execution:
   .github/workflows/pest.yml180

Sources: .github/workflows/pest.yml129-181

Complementary Quality Checks

Pest tests are part of a broader QA suite that includes:

• Syntax Checks: Validating PHP syntax against versions 8.3, 8.4, and 8.5 .github/workflows/syntax-php.yml19 and XML syntax using xmllint .github/workflows/syntax-xml.yml42-44
• Static Analysis: PHPStan for deep code analysis .github/workflows/phpstan.yml54
• Coding Standards: PHP-CS-Fixer for style validation .github/workflows/php-cs-fixer.yml40
• Rector: Automated refactoring and modernization .github/workflows/rector.yml40
• Copyright Validation: Ensuring files contain the required Maho license headers, matching a specific pattern including the current year .github/workflows/copyright.yml65
• Translation Integrity: Checking for missing .github/workflows/check-missing-translations.yml37 or unused .github/workflows/check-unused-translations.yml35 translations using dev:translations:* commands.

Sources: .github/workflows/syntax-php.yml1-65 .github/workflows/syntax-xml.yml1-60 .github/workflows/phpstan.yml1-62 .github/workflows/copyright.yml1-100 .github/workflows/rector.yml1-41 .github/workflows/php-cs-fixer.yml1-41 .github/workflows/check-missing-translations.yml1-46 .github/workflows/check-unused-translations.yml1-43