Skip to content

README.md

Latest commit

 

History

History
172 lines (131 loc) · 5.33 KB

README.md

File metadata and controls

172 lines (131 loc) · 5.33 KB
Raw

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