wp-plugin-starter-template-for-ai-coding/.wiki/Testing.md

Testing Framework

This document explains how to use the testing framework for our plugin.

Table of Contents

• Overview
• Prerequisites
• Testing Approaches
  • wp-env Approach
  • WordPress Playground Approach
• Writing Tests
• CI/CD Integration
• Troubleshooting
• PHPUnit Tests
• Future Improvements

Overview

Our testing framework uses:

See also:

• Architecture Overview – high-level design
• Multisite Development – deeper multisite guidance

Components:

• wp-env: For setting up WordPress environments (both single site and multisite)
• WordPress Playground: For browser-based testing without Docker
• Cypress: For end-to-end testing
• PHPUnit: For unit testing (coming soon)

Prerequisites

1. Node.js: Version 16 or higher
2. npm: For package management
3. Docker: For running WordPress environments with wp-env (not needed for WordPress Playground)
4. PHP: Version 7.4 or higher (for future PHPUnit tests)
5. Composer: For managing PHP dependencies

Testing Approaches

We provide two main approaches for testing:

1. wp-env: Traditional approach using Docker
2. WordPress Playground: Browser-based approach without Docker

1. wp-env Approach

Setting Up Test Environments

We provide scripts to easily set up test environments:

Single Site Environment

# Set up a single site environment
npm run setup:single

# You can also use the unified setup script:
bash bin/setup-test-env.sh single

This will:

1. Start a WordPress single site environment using wp-env
2. Install and activate our plugin
3. Configure WordPress for testing

Multisite Environment

# Set up a multisite environment
npm run setup:multisite

# Or via the setup script:
bash bin/setup-test-env.sh multisite

This will:

1. Start a WordPress multisite environment using wp-env
2. Install and activate our plugin network-wide
3. Create a test subsite
4. Configure WordPress for testing

Running Tests

We have Cypress tests for both single site and multisite environments:

Single Site Tests

# Run tests in browser (interactive mode)
npm run test:single

# Run tests headless (CI mode)
npm run test:single:headless

Multisite Tests

# Run tests in browser (interactive mode)
npm run test:multisite

# Run tests headless (CI mode)
npm run test:multisite:headless

All-in-One Commands

We also provide all-in-one commands that set up the environment and run the tests:

# Set up single site environment and run tests
npm run test:e2e:single

# Set up multisite environment and run tests
npm run test:e2e:multisite

2. WordPress Playground Approach

WordPress Playground runs WordPress entirely in the browser using WebAssembly. This means:

• No server required - WordPress runs in the browser
• Fast startup times
• Isolated testing environment
• Works well with CI/CD pipelines

Using WordPress Playground Online

The easiest way to test our plugin with WordPress Playground is to use the online version:

1. Single site testing: Open in WordPress Playground

2. Multisite testing: Open in WordPress Playground

These links automatically set up WordPress with multisite enabled and WP_DEBUG enabled.

Both the Plugin Toggle and Kadence Blocks plugins are pre-activated.

Local Testing with HTML Files

We've also included HTML files that embed WordPress Playground:

1. Open playground/index.html in your browser for single site testing
2. Open playground/multisite.html in your browser for multisite testing
3. Open playground/test.html in your browser for a unified interface with buttons to switch between single site and multisite

You can serve these files locally with a simple HTTP server:

# Using Python
python -m http.server 8888 --directory playground

# Then open http://localhost:8888/index.html in your browser
# Or open http://localhost:8888/test.html for a unified single/multisite switcher

Writing Tests

Cypress Tests

We have custom Cypress commands to make testing WordPress easier:

• cy.loginAsAdmin(): Logs in as the admin user
• cy.activatePlugin(pluginSlug): Activates a plugin
• cy.networkActivatePlugin(pluginSlug): Network activates a plugin in multisite

Example test:

describe('WordPress Single Site Tests', () => {
  it('Can login to the admin area', () => {
    cy.loginAsAdmin();
    cy.get('body.wp-admin').should('exist');
  });

  it('Plugin is activated', () => {
    cy.loginAsAdmin();
    cy.visit('/wp-admin/plugins.php');
    cy.get('tr[data-slug="wp-plugin-starter-template-for-ai-coding"]')
      .should('have.class', 'active');
  });
});

CI/CD Integration

We have GitHub Actions workflows for running tests in CI/CD:

• .github/workflows/wordpress-tests.yml: Runs wp-env e2e tests
• .github/workflows/playground-tests.yml: Runs Playground e2e tests
• .github/workflows/phpunit.yml: Runs PHPUnit tests (coming soon)

Troubleshooting

Common Issues

1. Docker not running: Make sure Docker is running before starting wp-env
2. Port conflicts: If ports 8888 or 8889 are in use, wp-env will fail to start
3. wp-env not installed: Run npm install -g @wordpress/env to install wp-env globally
4. WordPress Playground not loading: Check your network connection and try refreshing the page
5. Tests failing: Check the error messages in the console and fix the issues

Error Checking and Feedback Loops

For information on code quality issues and automated tool feedback, see the Error Checking and Feedback Loops documentation.

Debugging

1. Cypress debugging: Use cy.debug() to pause test execution
2. wp-env debugging: Run wp-env logs to see WordPress logs
3. GitHub Actions debugging: Check the workflow logs for detailed error messages

PHPUnit Tests

We use PHPUnit for unit testing PHP code. The tests are located in the tests/phpunit directory.

Running PHPUnit Tests

# Run PHPUnit tests for single site
npm run test:phpunit

# Run PHPUnit tests for multisite
npm run test:phpunit:multisite

Writing PHPUnit Tests

Here's an example of a PHPUnit test for the Multisite class:

<?php
class MultisiteTest extends WP_UnitTestCase {

    public function test_is_multisite_compatible() {
        $multisite = new WP_Plugin_Starter_Template_For_AI_Coding\Multisite\Multisite();
        $this->assertTrue($multisite->is_multisite_compatible());
    }

    public function test_get_network_sites() {
        $multisite = new WP_Plugin_Starter_Template_For_AI_Coding\Multisite\Multisite();
        $sites = $multisite->get_network_sites();
        $this->assertIsArray($sites);
    }
}

Future Improvements

1. Performance tests: Add performance testing
2. Accessibility tests: Add accessibility testing