Update WordPress Playground integration with Plugin Toggle and comprehensive documentation

.ai-workflows/code-review.md

@@ -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

.github/workflows/wordpress-tests.yml

@@ -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 test:playground:single"
-        echo "npm run setup:multisite && npm run test:multisite:headless"
+        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
+  # Use WordPress Playground for e2e tests
-  # e2e-test:
+  e2e-test:
-  #   name: End-to-End Tests
+    name: WordPress Playground Tests
-  #   runs-on: ubuntu-latest
+    runs-on: ubuntu-latest
-  #   needs: code-quality
+    needs: code-quality
-  #   steps:
+    steps:
-  #   - uses: actions/checkout@v4
+    - uses: actions/checkout@v4
-  #
+
-  #   - name: Setup Node.js
+    - name: Setup Node.js
-  #     uses: actions/setup-node@v4
+      uses: actions/setup-node@v4
-  #     with:
+      with:
-  #       node-version: '20'
+        node-version: '20'
-  #       cache: 'npm'
+        cache: 'npm'
-  #
+
-  #   - name: Install dependencies
+    - name: Install dependencies
-  #     run: npm ci
+      run: npm ci
-  #
+
-  #   - name: Install Cypress
+    - name: Install WordPress Playground CLI
-  #     run: npm install cypress
+      run: npm install -g @wordpress/playground-tools
-  #
+
-  #   - name: Wait for WordPress
+    - name: Create plugin zip
-  #     run: |
+      run: |
-  #       echo "Waiting for WordPress to be ready..."
+        mkdir -p dist
-  #       timeout 60 bash -c 'until curl -s http://localhost:8000; do sleep 2; done'
+        zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
-  #
+
-  #   - name: Run Cypress tests
+    - name: Run tests with WordPress Playground
-  #     run: |
+      run: |
-  #       echo "Running e2e tests..."
+        # Start WordPress Playground with our blueprint
-  #       # This is a placeholder for the actual test command
+        wp-playground start --blueprint playground/blueprint.json --port 8888 &
-  #       # npm run test:single:headless
+
+        # 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

.wiki/Playground-Testing.md

@@ -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)
+   - [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=17)
+   - [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.

.wiki/Testing.md

@@ -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
 

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:
 
-```bash
+1. Using WordPress Playground (no Docker required):
-npm run setup:multisite
+   * [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)
-```
 
-For more details on our testing approach, see the [Testing Framework](.wiki/Testing-Framework.md) file.
+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) and [Playground Testing](.wiki/Playground-Testing.md) documentation.
 
 ## Support & Feedback
 

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",
+    "test:e2e:single": "npm run setup:single && sleep 5 && npm run test:single:headless",
-    "setup:playground:multisite": "bash bin/setup-test-env.sh playground-multisite",
+    "test:e2e:multisite": "npm run setup:multisite && sleep 5 && npm run test:multisite:headless",
-    "test:playground:single": "npm run setup:playground:single && sleep 10 && cypress run --config specPattern=cypress/e2e/playground-single-site.cy.js",
+    "test:playground:single": "cypress run --config specPattern=cypress/e2e/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: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"
   }
 }

playground/blueprint.json

@@ -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"
       }
     }
   ]

playground/index.html

@@ -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>

playground/multisite-blueprint.json

@@ -15,7 +15,7 @@
     },
     {
       "step": "wp-cli",
-      "command": "wp plugin install hello-dolly --activate-network"
+      "command": "wp plugin install plugin-toggle --activate-network"
     }
   ]
 }

playground/multisite.html

@@ -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>