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

Testing Framework

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

Overview

Our testing framework uses:

• 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)

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

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

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

   • After WordPress loads, go to Settings > General
   • Scroll down and check "Allow network access" and "Create a multisite network"
   • Click "Apply Settings & Reset Playground"

These links will automatically set up WordPress with a sample plugin installed and 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

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

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/cypress.yml: Runs Cypress 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

Debugging

1. Cypress debugging: Use cy.debug() to pause test execution
2. wp-env debugging: Run wp-env logs to see WordPress logs

Future Improvements

1. PHPUnit tests: Add unit tests for PHP code
2. Performance tests: Add performance testing
3. Accessibility tests: Add accessibility testing