Update WordPress Playground integration with Plugin Toggle and comprehensive documentation
This commit is contained in:
@@ -4,6 +4,17 @@ This document provides guidance for AI assistants to help with code review for t
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
### Testing with WordPress Playground
|
||||
|
||||
Before submitting code for review, test it with WordPress Playground:
|
||||
|
||||
* [ ] Test in single site environment: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=5)
|
||||
* [ ] Test in multisite environment: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18)
|
||||
* [ ] Verify plugin functionality works in both environments
|
||||
* [ ] Check for any JavaScript errors in the browser console
|
||||
|
||||
For more details on WordPress Playground testing, see the [Playground Testing](.wiki/Playground-Testing.md) documentation.
|
||||
|
||||
When reviewing code, check for the following:
|
||||
|
||||
### Functionality
|
||||
|
||||
73
.github/workflows/wordpress-tests.yml
vendored
73
.github/workflows/wordpress-tests.yml
vendored
@@ -40,38 +40,45 @@ jobs:
|
||||
# Note about e2e tests
|
||||
- name: Note about e2e tests
|
||||
run: |
|
||||
echo "Note: e2e tests are temporarily disabled in CI due to Docker compatibility issues."
|
||||
echo "Note: We now use WordPress Playground for e2e tests instead of Docker."
|
||||
echo "Please run tests locally before submitting PRs using:"
|
||||
echo "npm run setup:single && npm run test:single:headless"
|
||||
echo "npm run setup:multisite && npm run test:multisite:headless"
|
||||
echo "npm run test:playground:single"
|
||||
echo "npm run test:playground:multisite"
|
||||
echo "Or use the online WordPress Playground links in the documentation."
|
||||
|
||||
# Temporarily disable e2e tests until we can fix the Docker service container issues
|
||||
# e2e-test:
|
||||
# name: End-to-End Tests
|
||||
# runs-on: ubuntu-latest
|
||||
# needs: code-quality
|
||||
# steps:
|
||||
# - uses: actions/checkout@v4
|
||||
#
|
||||
# - name: Setup Node.js
|
||||
# uses: actions/setup-node@v4
|
||||
# with:
|
||||
# node-version: '20'
|
||||
# cache: 'npm'
|
||||
#
|
||||
# - name: Install dependencies
|
||||
# run: npm ci
|
||||
#
|
||||
# - name: Install Cypress
|
||||
# run: npm install cypress
|
||||
#
|
||||
# - name: Wait for WordPress
|
||||
# run: |
|
||||
# echo "Waiting for WordPress to be ready..."
|
||||
# timeout 60 bash -c 'until curl -s http://localhost:8000; do sleep 2; done'
|
||||
#
|
||||
# - name: Run Cypress tests
|
||||
# run: |
|
||||
# echo "Running e2e tests..."
|
||||
# # This is a placeholder for the actual test command
|
||||
# # npm run test:single:headless
|
||||
# Use WordPress Playground for e2e tests
|
||||
e2e-test:
|
||||
name: WordPress Playground Tests
|
||||
runs-on: ubuntu-latest
|
||||
needs: code-quality
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Install WordPress Playground CLI
|
||||
run: npm install -g @wordpress/playground-tools
|
||||
|
||||
- name: Create plugin zip
|
||||
run: |
|
||||
mkdir -p dist
|
||||
zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
|
||||
|
||||
- name: Run tests with WordPress Playground
|
||||
run: |
|
||||
# Start WordPress Playground with our blueprint
|
||||
wp-playground start --blueprint playground/blueprint.json --port 8888 &
|
||||
|
||||
# Wait for WordPress Playground to be ready
|
||||
echo "Waiting for WordPress Playground to be ready..."
|
||||
timeout 60 bash -c 'until curl -s http://localhost:8888; do sleep 2; done'
|
||||
|
||||
# Run tests against WordPress Playground
|
||||
npm run test:playground:single
|
||||
|
||||
@@ -15,11 +15,75 @@ This document explains how to use WordPress Playground for testing our plugin.
|
||||
|
||||
The easiest way to test our plugin with WordPress Playground is to use the online version:
|
||||
|
||||
1. Single site testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=4)
|
||||
1. Single site testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=5)
|
||||
|
||||
2. Multisite testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=17)
|
||||
2. Multisite testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18)
|
||||
|
||||
These links will automatically set up WordPress with multisite enabled and the Hello Dolly plugin network-activated.
|
||||
These links will automatically set up WordPress with multisite enabled and the Plugin Toggle plugin network-activated.
|
||||
|
||||
## WP-CLI Commands for WordPress Playground
|
||||
|
||||
WordPress Playground supports WP-CLI commands, which can be used to interact with WordPress programmatically. Here are some useful commands for testing:
|
||||
|
||||
### General Commands
|
||||
|
||||
```bash
|
||||
# Get WordPress version
|
||||
wp core version
|
||||
|
||||
# List installed plugins
|
||||
wp plugin list
|
||||
|
||||
# Install a plugin
|
||||
wp plugin install plugin-slug
|
||||
|
||||
# Activate a plugin
|
||||
wp plugin activate plugin-slug
|
||||
|
||||
# Deactivate a plugin
|
||||
wp plugin deactivate plugin-slug
|
||||
|
||||
# Get plugin status
|
||||
wp plugin status plugin-slug
|
||||
```
|
||||
|
||||
### Multisite Commands
|
||||
|
||||
```bash
|
||||
# List all sites in the network
|
||||
wp site list
|
||||
|
||||
# Create a new site
|
||||
wp site create --slug=testsite
|
||||
|
||||
# Delete a site
|
||||
wp site delete 2
|
||||
|
||||
# Network activate a plugin
|
||||
wp plugin activate plugin-slug --network
|
||||
|
||||
# Activate a plugin for a specific site
|
||||
wp plugin activate plugin-slug --url=example.com/testsite
|
||||
|
||||
# Create a new user and add them to a site
|
||||
wp user create testuser test@example.com --role=editor
|
||||
wp user add-role testuser editor --url=example.com/testsite
|
||||
```
|
||||
|
||||
### Testing Commands
|
||||
|
||||
```bash
|
||||
# Run a specific test
|
||||
wp scaffold plugin-tests my-plugin
|
||||
wp test run --filter=test_function_name
|
||||
|
||||
# Check for PHP errors
|
||||
wp site health check
|
||||
|
||||
# Export/import content for testing
|
||||
wp export
|
||||
wp import
|
||||
```
|
||||
|
||||
## Plugin Activation in Multisite
|
||||
|
||||
@@ -35,7 +99,7 @@ In a WordPress multisite environment, there are two ways to activate plugins:
|
||||
- Go to Plugins and activate the plugin for that site only
|
||||
- Or use WP-CLI: `wp plugin activate plugin-name --url=site-url`
|
||||
|
||||
Our multisite blueprint uses network activation for the Hello Dolly plugin as an example.
|
||||
Our multisite blueprint uses network activation for the Plugin Toggle plugin as an example.
|
||||
|
||||
## Running Tests with WordPress Playground
|
||||
|
||||
@@ -47,8 +111,8 @@ We have two blueprints for testing:
|
||||
To run tests with WordPress Playground:
|
||||
|
||||
1. Open the appropriate WordPress Playground link:
|
||||
- [Single site](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=4)
|
||||
- [Multisite](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=17)
|
||||
- [Single site](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=5)
|
||||
- [Multisite](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18)
|
||||
|
||||
2. Test the plugin manually in the browser
|
||||
|
||||
@@ -72,10 +136,124 @@ python -m http.server 8888 --directory playground
|
||||
|
||||
You can customize the blueprints to suit your testing needs. See the [WordPress Playground Blueprints documentation](https://wordpress.github.io/wordpress-playground/blueprints/) for more information.
|
||||
|
||||
## WordPress Playground JavaScript API
|
||||
|
||||
WordPress Playground provides a JavaScript API that allows you to programmatically interact with WordPress. This is useful for automated testing and CI/CD integration.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```javascript
|
||||
// Import the WordPress Playground client
|
||||
import { createWordPressPlayground } from '@wp-playground/client';
|
||||
|
||||
// Create a playground instance
|
||||
const playground = await createWordPressPlayground({
|
||||
iframe: document.getElementById('wp-playground'),
|
||||
remoteUrl: 'https://playground.wordpress.net/remote.html',
|
||||
});
|
||||
|
||||
// Run a blueprint
|
||||
await playground.run({
|
||||
steps: [
|
||||
{ step: 'enableMultisite' },
|
||||
{ step: 'wp-cli', command: 'wp site create --slug=testsite' },
|
||||
{ step: 'wp-cli', command: 'wp plugin install plugin-toggle --activate-network' }
|
||||
]
|
||||
});
|
||||
|
||||
// Run WP-CLI commands
|
||||
const result = await playground.run({
|
||||
step: 'wp-cli',
|
||||
command: 'wp plugin list --format=json'
|
||||
});
|
||||
|
||||
// Parse the JSON output
|
||||
const plugins = JSON.parse(result.output);
|
||||
console.log(plugins);
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
You can use the JavaScript API with testing frameworks like Jest or Cypress:
|
||||
|
||||
```javascript
|
||||
describe('Plugin Tests', () => {
|
||||
let playground;
|
||||
|
||||
beforeAll(async () => {
|
||||
playground = await createWordPressPlayground({
|
||||
iframe: document.getElementById('wp-playground'),
|
||||
remoteUrl: 'https://playground.wordpress.net/remote.html',
|
||||
});
|
||||
|
||||
// Set up WordPress with our blueprint
|
||||
await playground.run({
|
||||
steps: [
|
||||
{ step: 'enableMultisite' },
|
||||
{ step: 'wp-cli', command: 'wp site create --slug=testsite' },
|
||||
{ step: 'wp-cli', command: 'wp plugin install plugin-toggle --activate-network' }
|
||||
]
|
||||
});
|
||||
});
|
||||
|
||||
test('Plugin is activated', async () => {
|
||||
const result = await playground.run({
|
||||
step: 'wp-cli',
|
||||
command: 'wp plugin list --format=json'
|
||||
});
|
||||
|
||||
const plugins = JSON.parse(result.output);
|
||||
const pluginToggle = plugins.find(plugin => plugin.name === 'plugin-toggle');
|
||||
expect(pluginToggle.status).toBe('active');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
We have a GitHub Actions workflow that uses WordPress Playground for testing. See `.github/workflows/playground-tests.yml` for more information.
|
||||
|
||||
### Example GitHub Actions Workflow
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
playground-test:
|
||||
name: WordPress Playground Tests
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Install WordPress Playground CLI
|
||||
run: npm install -g @wordpress/playground-tools
|
||||
|
||||
- name: Create plugin zip
|
||||
run: |
|
||||
mkdir -p dist
|
||||
zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
|
||||
|
||||
- name: Run tests with WordPress Playground
|
||||
run: |
|
||||
# Start WordPress Playground with our blueprint
|
||||
wp-playground start --blueprint playground/blueprint.json --port 8888 &
|
||||
|
||||
# Wait for WordPress Playground to be ready
|
||||
echo "Waiting for WordPress Playground to be ready..."
|
||||
timeout 60 bash -c 'until curl -s http://localhost:8888; do sleep 2; done'
|
||||
|
||||
# Run Cypress tests against WordPress Playground
|
||||
npm run test:single:headless
|
||||
```
|
||||
|
||||
## Performance Testing
|
||||
|
||||
We also use the [WP Performance Tests GitHub Action](https://github.com/marketplace/actions/wp-performance-tests) for performance testing. This action tests our plugin against various WordPress versions and PHP versions to ensure it performs well in different environments.
|
||||
|
||||
@@ -104,11 +104,11 @@ WordPress Playground runs WordPress entirely in the browser using WebAssembly. T
|
||||
|
||||
The easiest way to test our plugin with WordPress Playground is to use the online version:
|
||||
|
||||
1. Single site testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=4)
|
||||
1. Single site testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=5)
|
||||
|
||||
2. Multisite testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=17)
|
||||
2. Multisite testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18)
|
||||
|
||||
These links will automatically set up WordPress with multisite enabled and the Hello Dolly plugin network-activated.
|
||||
These links will automatically set up WordPress with multisite enabled and the Plugin Toggle plugin network-activated.
|
||||
|
||||
#### Local Testing with HTML Files
|
||||
|
||||
|
||||
20
README.md
20
README.md
@@ -101,7 +101,17 @@ This template includes configuration for WordPress Environment (wp-env) to make
|
||||
|
||||
### Testing
|
||||
|
||||
The template includes both PHP unit tests and end-to-end tests:
|
||||
The template includes multiple testing approaches:
|
||||
|
||||
#### WordPress Playground Testing (No Docker Required)
|
||||
|
||||
Test your plugin directly in the browser without any local setup:
|
||||
|
||||
1. Single site testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=5)
|
||||
|
||||
2. Multisite testing: [Open in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18)
|
||||
|
||||
For more details, see the [Playground Testing](.wiki/Playground-Testing.md) documentation.
|
||||
|
||||
#### PHP Unit Tests
|
||||
|
||||
@@ -221,13 +231,17 @@ Customize the includes/core.php file to implement your core functionality and th
|
||||
|
||||
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:
|
||||
You can test multisite compatibility in two ways:
|
||||
|
||||
1. Using WordPress Playground (no Docker required):
|
||||
* [Open Multisite in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18)
|
||||
|
||||
2. Using wp-env (requires Docker):
|
||||
```bash
|
||||
npm run setup:multisite
|
||||
```
|
||||
|
||||
For more details on our testing approach, see the [Testing Framework](.wiki/Testing-Framework.md) file.
|
||||
For more details on our testing approach, see the [Testing Framework](.wiki/Testing-Framework.md) and [Playground Testing](.wiki/Playground-Testing.md) documentation.
|
||||
|
||||
## Support & Feedback
|
||||
|
||||
|
||||
10
package.json
10
package.json
@@ -13,10 +13,10 @@
|
||||
"test:single:headless": "cypress run --config specPattern=cypress/e2e/single-site.cy.js",
|
||||
"test:multisite": "cypress open --config specPattern=cypress/e2e/multisite.cy.js",
|
||||
"test:multisite:headless": "cypress run --config specPattern=cypress/e2e/multisite.cy.js",
|
||||
"setup:playground:single": "bash bin/setup-test-env.sh playground-single",
|
||||
"setup:playground:multisite": "bash bin/setup-test-env.sh playground-multisite",
|
||||
"test:playground:single": "npm run setup:playground:single && sleep 10 && cypress run --config specPattern=cypress/e2e/playground-single-site.cy.js",
|
||||
"test:playground:multisite": "npm run setup:playground:multisite && sleep 10 && cypress run --config specPattern=cypress/e2e/playground-multisite.cy.js",
|
||||
"test:e2e:single": "npm run setup:single && sleep 5 && npm run test:single:headless",
|
||||
"test:e2e:multisite": "npm run setup:multisite && sleep 5 && npm run test:multisite:headless",
|
||||
"test:playground:single": "cypress run --config specPattern=cypress/e2e/single-site.cy.js",
|
||||
"test:playground:multisite": "cypress run --config specPattern=cypress/e2e/multisite.cy.js",
|
||||
"build": "./build.sh",
|
||||
"lint:php": "composer run-script phpcs",
|
||||
"lint:php:simple": "composer run-script phpcs:simple",
|
||||
@@ -50,6 +50,6 @@
|
||||
"@wordpress/env": "^8.12.0",
|
||||
"@wp-playground/blueprints": "^1.0.28",
|
||||
"@wp-playground/client": "^1.0.28",
|
||||
"cypress": "^13.6.4"
|
||||
"cypress": "^13.17.0"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
{
|
||||
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
|
||||
"landingPage": "/wp-admin/",
|
||||
"login": true,
|
||||
"steps": [
|
||||
@@ -6,7 +7,7 @@
|
||||
"step": "installPlugin",
|
||||
"pluginData": {
|
||||
"resource": "wordpress.org/plugins",
|
||||
"slug": "coblocks"
|
||||
"slug": "plugin-toggle"
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
@@ -20,6 +20,6 @@
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=4"></iframe>
|
||||
<iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/blueprint.json&_t=5"></iframe>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
},
|
||||
{
|
||||
"step": "wp-cli",
|
||||
"command": "wp plugin install hello-dolly --activate-network"
|
||||
"command": "wp plugin install plugin-toggle --activate-network"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -20,6 +20,6 @@
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=17"></iframe>
|
||||
<iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/feature/testing-framework/playground/multisite-blueprint.json&_t=18"></iframe>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user