From 8ed22642e2e16cdaf68f012d45410f179c831038 Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Mon, 21 Apr 2025 17:32:01 +0100 Subject: [PATCH] Add comprehensive testing framework for both single site and multisite WordPress environments --- .github/workflows/wordpress-tests.yml | 68 ++++++++++++++ .wiki/Testing-Framework.md | 125 ++++++++++++++++++++++++++ .wp-env.json | 16 ++++ .wp-env.multisite.json | 22 +++++ README.md | 18 +++- bin/setup-test-env.sh | 59 ++++++++++++ cypress.config.js | 10 +++ cypress/e2e/multisite.cy.js | 43 +++++++++ cypress/e2e/single-site.cy.js | 26 ++++++ mu-plugins/multisite-setup.php | 33 +++++++ package.json | 9 +- 11 files changed, 422 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/wordpress-tests.yml create mode 100644 .wiki/Testing-Framework.md create mode 100644 .wp-env.json create mode 100644 .wp-env.multisite.json create mode 100644 bin/setup-test-env.sh create mode 100644 cypress.config.js create mode 100644 cypress/e2e/multisite.cy.js create mode 100644 cypress/e2e/single-site.cy.js create mode 100644 mu-plugins/multisite-setup.php diff --git a/.github/workflows/wordpress-tests.yml b/.github/workflows/wordpress-tests.yml new file mode 100644 index 0000000..cde5f28 --- /dev/null +++ b/.github/workflows/wordpress-tests.yml @@ -0,0 +1,68 @@ +name: WordPress Environment Tests + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + single-site-test: + name: Single Site Tests + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '16' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Install wp-env + run: npm install -g @wordpress/env + + - name: Setup WordPress Single Site + run: | + chmod +x bin/setup-test-env.sh + bash bin/setup-test-env.sh single + + - name: Install Cypress + run: npm install cypress + + - name: Run Cypress tests + run: npm run test:single:headless + + multisite-test: + name: Multisite Tests + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '16' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Install wp-env + run: npm install -g @wordpress/env + + - name: Setup WordPress Multisite + run: | + chmod +x bin/setup-test-env.sh + bash bin/setup-test-env.sh multisite + + - name: Install Cypress + run: npm install cypress + + - name: Run Cypress tests + run: npm run test:multisite:headless diff --git a/.wiki/Testing-Framework.md b/.wiki/Testing-Framework.md new file mode 100644 index 0000000..3fbc16f --- /dev/null +++ b/.wiki/Testing-Framework.md @@ -0,0 +1,125 @@ +# WordPress Plugin Testing Framework + +This document outlines how to set up and run tests for our plugin in both single site and multisite WordPress environments. + +## Overview + +Our plugin is designed to work with both standard WordPress installations and WordPress Multisite. This testing framework allows you to verify functionality in both environments. + +## Setting Up the Test Environment + +We use `@wordpress/env` and Cypress for testing our plugin. + +### Prerequisites + +* Node.js (v14 or higher) +* npm or yarn +* Docker and Docker Compose + +### Installation + +1. Clone the repository: + ```bash + git clone https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding.git + cd wp-plugin-starter-template-for-ai-coding + ``` + +2. Install dependencies: + ```bash + npm install + ``` + +## Testing in Single Site WordPress + +1. Set up the single site environment: + ```bash + npm run setup:single + ``` + + This will: + - Start a WordPress environment using wp-env + - Activate our plugin + +2. Run Cypress tests for single site: + ```bash + npm run test:single + ``` + + For headless testing: + ```bash + npm run test:single:headless + ``` + +3. Access the site manually: + - Site: http://localhost:8888 + - Admin login: admin / password + +## Testing in WordPress Multisite + +1. Set up the multisite environment: + ```bash + npm run setup:multisite + ``` + + This will: + - Start a WordPress environment using wp-env + - Configure it as a multisite installation + - Create a test subsite + - Network activate our plugin + +2. Run Cypress tests for multisite: + ```bash + npm run test:multisite + ``` + + For headless testing: + ```bash + npm run test:multisite:headless + ``` + +3. Access the sites manually: + - Main site: http://localhost:8888 + - Test subsite: http://localhost:8888/testsite + - Admin login: admin / password + +## Continuous Integration + +We use GitHub Actions to automatically run tests on pull requests. The workflow is defined in `.github/workflows/wordpress-tests.yml` and runs tests in both single site and multisite environments. + +## Writing Tests + +### Single Site Tests + +Add new single site tests to `cypress/e2e/single-site.cy.js`. + +### Multisite Tests + +Add new multisite tests to `cypress/e2e/multisite.cy.js`. + +## Troubleshooting + +### Common Issues + +1. **Database connection errors**: Make sure Docker is running and ports 8888 and 8889 are available. + +2. **Multisite conversion fails**: Check the wp-env logs for details: + ```bash + wp-env logs + ``` + +3. **Plugin not activated**: Run the following command: + ```bash + # For single site + wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding + + # For multisite + wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding --network + ``` + +### Getting Help + +If you encounter any issues, please open an issue on our GitHub repository with: +- A description of the problem +- Steps to reproduce +- Any error messages +- Your environment details (OS, Node.js version, etc.) diff --git a/.wp-env.json b/.wp-env.json new file mode 100644 index 0000000..87f327f --- /dev/null +++ b/.wp-env.json @@ -0,0 +1,16 @@ +{ + "core": null, + "plugins": [ + "." + ], + "themes": [], + "config": { + "WP_DEBUG": true, + "WP_DEBUG_LOG": true, + "WP_DEBUG_DISPLAY": false + }, + "mappings": { + "wp-content/mu-plugins": "./mu-plugins", + "wp-content/plugins/wp-plugin-starter-template-for-ai-coding": "." + } +} diff --git a/.wp-env.multisite.json b/.wp-env.multisite.json new file mode 100644 index 0000000..1306cf3 --- /dev/null +++ b/.wp-env.multisite.json @@ -0,0 +1,22 @@ +{ + "core": null, + "plugins": [ + "." + ], + "themes": [], + "config": { + "WP_DEBUG": true, + "WP_DEBUG_LOG": true, + "WP_DEBUG_DISPLAY": false, + "WP_ALLOW_MULTISITE": true, + "MULTISITE": true, + "SUBDOMAIN_INSTALL": false, + "PATH_CURRENT_SITE": "/", + "SITE_ID_CURRENT_SITE": 1, + "BLOG_ID_CURRENT_SITE": 1 + }, + "mappings": { + "wp-content/mu-plugins": "./mu-plugins", + "wp-content/plugins/wp-plugin-starter-template-for-ai-coding": "." + } +} diff --git a/README.md b/README.md index affe26f..19d9416 100644 --- a/README.md +++ b/README.md @@ -85,11 +85,17 @@ This template includes configuration for WordPress Environment (wp-env) to make npm run start ``` -3. For multisite testing: +3. For testing in different WordPress environments: ```bash - npm run multisite + # For single site testing + npm run setup:single + + # For multisite testing + npm run setup:multisite ``` + See [Testing Framework](.wiki/Testing-Framework.md) for more details on our testing approach. + 4. Access your local WordPress site at (admin credentials: admin/password) ### Testing @@ -212,12 +218,16 @@ Customize the includes/core.php file to implement your core functionality and th ### Is this template compatible with WordPress multisite? -Yes, this template is fully compatible with WordPress multisite installations. You can test multisite compatibility by running: +Yes, this template is fully compatible with WordPress multisite installations. We have a comprehensive testing framework that allows you to verify functionality in both single site and multisite environments. + +You can test multisite compatibility by running: ```bash -npm run multisite +npm run setup:multisite ``` +For more details on our testing approach, see the [Testing Framework](.wiki/Testing-Framework.md) file. + ## Support & Feedback If you need help with this template, there are several ways to get support: diff --git a/bin/setup-test-env.sh b/bin/setup-test-env.sh new file mode 100644 index 0000000..14150d5 --- /dev/null +++ b/bin/setup-test-env.sh @@ -0,0 +1,59 @@ +#!/bin/bash + +# Make the bin directory executable +chmod +x bin + +# Check if wp-env is installed +if ! command -v wp-env &> /dev/null; then + echo "wp-env is not installed. Installing..." + npm install -g @wordpress/env +fi + +# Check if environment type is provided +if [ -z "$1" ]; then + echo "Usage: $0 [single|multisite]" + exit 1 +fi + +ENV_TYPE=$1 + +if [ "$ENV_TYPE" == "single" ]; then + echo "Setting up single site environment..." + + # Start the environment + wp-env start + + # Wait for WordPress to be ready + sleep 5 + + # Activate our plugin + wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding + + echo "WordPress Single Site environment is ready!" + echo "Site: http://localhost:8888" + echo "Admin login: admin / password" + +elif [ "$ENV_TYPE" == "multisite" ]; then + echo "Setting up multisite environment..." + + # Start the environment with multisite configuration + wp-env start --config=.wp-env.multisite.json + + # Wait for WordPress to be ready + sleep 5 + + # Create a test site + wp-env run cli wp site create --slug=testsite --title="Test Site" --email=admin@example.com + + # Network activate our plugin + wp-env run cli wp plugin activate wp-plugin-starter-template-for-ai-coding --network + + echo "WordPress Multisite environment is ready!" + echo "Main site: http://localhost:8888" + echo "Test site: http://localhost:8888/testsite" + echo "Admin login: admin / password" + +else + echo "Invalid environment type. Use 'single' or 'multisite'." + exit 1 +fi diff --git a/cypress.config.js b/cypress.config.js new file mode 100644 index 0000000..d22986e --- /dev/null +++ b/cypress.config.js @@ -0,0 +1,10 @@ +const { defineConfig } = require('cypress'); + +module.exports = defineConfig({ + e2e: { + baseUrl: 'http://localhost:8888', + setupNodeEvents(on, config) { + // implement node event listeners here + }, + }, +}); diff --git a/cypress/e2e/multisite.cy.js b/cypress/e2e/multisite.cy.js new file mode 100644 index 0000000..ee68f29 --- /dev/null +++ b/cypress/e2e/multisite.cy.js @@ -0,0 +1,43 @@ +describe('WordPress Multisite Tests', () => { + it('Can access the main site', () => { + cy.visit('/'); + cy.get('body').should('exist'); + }); + + it('Can access the test subsite', () => { + cy.visit('/testsite'); + cy.get('body').should('exist'); + }); + + it('Can login to the admin area', () => { + cy.visit('/wp-admin'); + cy.get('#user_login').type('admin'); + cy.get('#user_pass').type('password'); + cy.get('#wp-submit').click(); + cy.get('body.wp-admin').should('exist'); + }); + + it('Can access network admin', () => { + // Login first + cy.visit('/wp-admin'); + cy.get('#user_login').type('admin'); + cy.get('#user_pass').type('password'); + cy.get('#wp-submit').click(); + + // Go to network admin + cy.visit('/wp-admin/network/'); + cy.get('body.network-admin').should('exist'); + }); + + it('Plugin is network activated', () => { + // Login first + cy.visit('/wp-admin'); + cy.get('#user_login').type('admin'); + cy.get('#user_pass').type('password'); + cy.get('#wp-submit').click(); + + // Check plugins page + cy.visit('/wp-admin/network/plugins.php'); + cy.contains('tr', 'WP Plugin Starter Template').should('contain', 'Network Active'); + }); +}); diff --git a/cypress/e2e/single-site.cy.js b/cypress/e2e/single-site.cy.js new file mode 100644 index 0000000..f016ed9 --- /dev/null +++ b/cypress/e2e/single-site.cy.js @@ -0,0 +1,26 @@ +describe('WordPress Single Site Tests', () => { + it('Can access the site', () => { + cy.visit('/'); + cy.get('body').should('exist'); + }); + + it('Can login to the admin area', () => { + cy.visit('/wp-admin'); + cy.get('#user_login').type('admin'); + cy.get('#user_pass').type('password'); + cy.get('#wp-submit').click(); + cy.get('body.wp-admin').should('exist'); + }); + + it('Plugin is activated', () => { + // Login first + cy.visit('/wp-admin'); + cy.get('#user_login').type('admin'); + cy.get('#user_pass').type('password'); + cy.get('#wp-submit').click(); + + // Check plugins page + cy.visit('/wp-admin/plugins.php'); + cy.contains('tr', 'WP Plugin Starter Template').should('contain', 'Deactivate'); + }); +}); diff --git a/mu-plugins/multisite-setup.php b/mu-plugins/multisite-setup.php new file mode 100644 index 0000000..393b5b7 --- /dev/null +++ b/mu-plugins/multisite-setup.php @@ -0,0 +1,33 @@ +