Ralph WP Testing

WordPress plugin with full PHPUnit test coverage, designed for automated testing with Ralph.

Overview

This project demonstrates how to set up comprehensive WordPress plugin testing using:

• wp-env — Docker-based WordPress development environment
• PHPUnit — Unit and integration testing framework
• WordPress Test Library — Official WP testing utilities
• Ralph — Copilot CLI runner for iterative development

Project Structure

ralph-wp-testing/
├── .wp-env.json                     # wp-env Docker configuration
├── package.json                     # npm scripts for wp-env
├── ralph.sh                         # Main Ralph loop
├── ralph-once.sh                    # Single Ralph iteration
├── ralph-worktree.sh                # Run Ralph in git worktree
├── ralph-stop.sh                    # Stop Ralph and cleanup
├── progress.txt                     # Ralph progress tracking
├── prompts/
│   └── wp-testing-agent.txt         # Ralph prompt for this project
├── plans/
│   └── prd.json                     # Ralph work items (8 items)
├── sample-plugin/
│   ├── sample-plugin.php            # Main plugin file
│   ├── composer.json                # PHP dependencies
│   ├── phpunit.xml.dist             # PHPUnit configuration
│   ├── phpcs.xml.dist               # PHP CodeSniffer rules
│   ├── includes/
│   │   ├── class-book-cpt.php       # Book custom post type
│   │   ├── class-genre-taxonomy.php # Genre taxonomy
│   │   ├── class-settings.php       # Settings page
│   │   ├── class-rest-api.php       # REST API endpoints
│   │   └── class-meta-box.php       # Book details meta box
│   └── tests/
│       ├── bootstrap.php            # Test bootstrapper
│       └── Unit/
│           ├── Test_Book_CPT.php
│           ├── Test_Genre_Taxonomy.php
│           ├── Test_Settings.php
│           ├── Test_REST_API.php
│           ├── Test_Meta_Box.php
│           └── Test_Activation.php
└── .github/
    └── workflows/
        └── phpunit.yml              # CI workflow

Quick Start

Prerequisites

• Docker Desktop running
• Node.js 18+ and npm
• PHP 8.1+ (for local Composer)

Setup

# Install npm dependencies (wp-env)
npm install

# Install PHP dependencies
cd sample-plugin && composer install && cd ..

# Start WordPress environment
npm run env:start

# Run tests
npm test

Available Commands

Command	Description
npm run env:start	Start wp-env Docker containers
npm run env:stop	Stop wp-env containers
npm run env:destroy	Remove wp-env containers and data
npm test	Run PHPUnit tests
npm run test:watch	Run tests with testdox output
npm run lint	Run PHP CodeSniffer

Running with Ralph

Ralph is a Copilot CLI wrapper that iteratively implements features from a PRD (Product Requirements Document).

Ralph Scripts

This project includes Ralph scripts for easy execution:

Script	Description
./ralph-worktree.sh	Run Ralph in an isolated git worktree
./ralph-stop.sh	Stop Ralph and clean up worktree
./ralph.sh	Main Ralph loop (used by worktree script)
./ralph-once.sh	Single Ralph iteration

Quick Start with Ralph

# Run Ralph in a worktree (recommended)
./ralph-worktree.sh

# Or with custom worktree name and iterations
./ralph-worktree.sh my-feature 5

# Stop Ralph and optionally remove worktree
./ralph-stop.sh

The worktree approach keeps your main branch clean while Ralph works.

Manual Ralph Execution

# Run Ralph directly
./ralph.sh --prompt prompts/wp-testing-agent.txt \
  --prd plans/prd.json \
  --allow-profile dev 10

PRD Work Items

The plans/prd.json contains 8 work items:

1. testing-setup — Verify wp-env and PHPUnit work
2. testing — Book CPT tests
3. testing — Genre taxonomy tests
4. testing — Settings API tests
5. testing — REST API endpoint tests
6. testing — Meta box tests
7. testing — Activation/deactivation hook tests
8. ci — GitHub Actions workflow

Test Coverage

Test File	Tests	Coverage
Test_Book_CPT.php	6	CPT registration, supports, CRUD
Test_Genre_Taxonomy.php	7	Taxonomy registration, terms, assignments
Test_Settings.php	8	Options, defaults, sanitization, capabilities
Test_REST_API.php	11	Endpoints, auth, CRUD, pagination
Test_Meta_Box.php	9	Nonce, capabilities, validation
Test_Activation.php	8	Hooks, options, transients

Plugin Features

The sample plugin includes:

• Book Custom Post Type — With title, editor, thumbnail, excerpt support
• Genre Taxonomy — Hierarchical taxonomy for categorizing books
• Settings Page — Under Settings menu with sanitization
• REST API — Custom endpoints at /wp-json/sample-plugin/v1/books
• Meta Box — Book details (author, ISBN, year, pages)

CI/CD

GitHub Actions runs:

• PHPUnit on PHP 8.1, 8.2, 8.3
• WordPress 6.6, 6.7, and latest
• PHP CodeSniffer for coding standards

License

GPL-2.0-or-later