marcusquinn
b58036f3f5
- Break long lines in documentation files to stay under 120 characters - Use reference-style links for long URLs - Simplify ASCII art diagram in error-checking-feedback-loops.md - Reorganize README.md badges with reference-style links
264 lines
7.4 KiB
Markdown
264 lines
7.4 KiB
Markdown
# Testing Framework
|
||
|
||
This document explains how to use the testing framework for our plugin.
|
||
|
||
## Table of Contents
|
||
|
||
* [Overview](#overview)
|
||
* [Prerequisites](#prerequisites)
|
||
* [Testing Approaches](#testing-approaches)
|
||
* [wp-env Approach](#1-wp-env-approach)
|
||
* [WordPress Playground Approach](#2-wordpress-playground-approach)
|
||
* [Writing Tests](#writing-tests)
|
||
* [CI/CD Integration](#cicd-integration)
|
||
* [Troubleshooting](#troubleshooting)
|
||
* [PHPUnit Tests](#phpunit-tests)
|
||
* [Future Improvements](#future-improvements)
|
||
|
||
## Overview
|
||
|
||
Our testing framework uses:
|
||
|
||
See also:
|
||
|
||
* [Architecture Overview](Architecture-Overview.md) – high-level design
|
||
* [Multisite Development](Multisite-Development.md) – 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# Run tests in browser (interactive mode)
|
||
npm run test:single
|
||
|
||
# Run tests headless (CI mode)
|
||
npm run test:single:headless
|
||
```
|
||
|
||
##### Multisite Tests
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# 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][playground-single]
|
||
|
||
2. Multisite testing: [Open in WordPress Playground][playground-multisite]
|
||
|
||
[playground-single]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json&_t=2
|
||
[playground-multisite]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/multisite-blueprint.json&_t=2
|
||
|
||
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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```javascript
|
||
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](Error-Checking-Feedback-Loops.md) 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
|
||
|
||
```bash
|
||
# 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
|
||
<?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
|
||
|