claude-plugin-wordpress-manager 1.4.0 → 1.7.0

package/skills/wp-e2e-testing/references/ci-integration.md

@@ -0,0 +1,174 @@
+# CI Pipeline Integration for WordPress Tests
+
+Use this file when setting up GitHub Actions (or similar CI) for WordPress test automation.
+
+## GitHub Actions workflow
+
+```yaml
+# .github/workflows/tests.yml
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  php-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php: ['8.1', '8.2', '8.3']
+        wp: ['6.8', '6.9']
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: wordpress_test
+        ports: ['3306:3306']
+        options: >-
+          --health-cmd="mysqladmin ping"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: mysqli
+          coverage: xdebug
+
+      - name: Cache Composer
+        uses: actions/cache@v4
+        with:
+          path: vendor
+          key: composer-${{ hashFiles('composer.lock') }}
+
+      - name: Install dependencies
+        run: composer install --no-interaction
+
+      - name: Install WP test suite
+        run: bash bin/install-wp-tests.sh wordpress_test root root 127.0.0.1 ${{ matrix.wp }}
+
+      - name: Run PHPUnit
+        run: vendor/bin/phpunit
+
+  js-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: Run Jest
+        run: npx wp-scripts test-unit-js --ci --coverage
+
+  e2e-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 Playwright browsers
+        run: npx playwright install chromium --with-deps
+
+      - name: Start wp-env
+        run: npx wp-env start
+
+      - name: Run Playwright tests
+        run: npx wp-scripts test-playwright
+
+      - name: Upload artifacts on failure
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-artifacts
+          path: artifacts/
+          retention-days: 7
+```
+
+## Caching strategies
+
+```yaml
+# Node modules
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: npm-${{ hashFiles('package-lock.json') }}
+
+# Playwright browsers
+- uses: actions/cache@v4
+  with:
+    path: ~/.cache/ms-playwright
+    key: playwright-${{ hashFiles('package-lock.json') }}
+
+# Docker images for wp-env
+- uses: ScribeMD/docker-cache@0.5.0
+  with:
+    key: docker-${{ hashFiles('.wp-env.json') }}
+```
+
+## Parallel test execution
+
+Split Playwright tests across multiple workers:
+
+```yaml
+e2e-tests:
+  strategy:
+    matrix:
+      shard: [1, 2, 3]
+  steps:
+    # ...
+    - run: npx playwright test --shard=${{ matrix.shard }}/3
+```
+
+## PHPUnit without wp-env (standalone)
+
+For projects that don't use wp-env, the `install-wp-tests.sh` script sets up the WP test suite:
+
+```bash
+bash bin/install-wp-tests.sh wordpress_test root root 127.0.0.1 latest true
+```
+
+Arguments: `db_name db_user db_pass db_host wp_version skip_db_create`
+
+## Conditional jobs
+
+Run expensive E2E tests only when relevant files change:
+
+```yaml
+e2e-tests:
+  if: |
+    contains(github.event.pull_request.labels.*.name, 'e2e') ||
+    github.ref == 'refs/heads/main'
+```
+
+## Best practices
+
+- Run PHPUnit with matrix strategy for PHP/WP version coverage
+- Cache aggressively (npm, Composer, Playwright browsers, Docker)
+- Upload test artifacts (traces, screenshots) on failure for debugging
+- Use `--ci` flag for Jest to disable interactive mode
+- Set reasonable timeouts to catch hanging tests early
+- Run lint/format checks as a separate job (fast fail)

package/skills/wp-e2e-testing/references/jest-wordpress.md

@@ -0,0 +1,114 @@
+# Jest for WordPress JavaScript Testing
+
+Use this file when writing or configuring Jest unit tests for WordPress JavaScript code.
+
+## Setup with @wordpress/scripts
+
+`@wordpress/scripts` includes a preconfigured Jest setup. No separate Jest config needed:
+
+```bash
+npm install -D @wordpress/scripts
+```
+
+Add to `package.json`:
+```json
+{
+  "scripts": {
+    "test:unit": "wp-scripts test-unit-js",
+    "test:unit:watch": "wp-scripts test-unit-js --watch"
+  }
+}
+```
+
+## Test file location
+
+By convention, tests go in:
+- `src/component/__tests__/component.test.js` — colocated with source
+- `src/component/test/component.test.js` — `test/` subdirectory
+- `tests/js/` — separate test directory (configure in `jest.config.js`)
+
+## Writing tests
+
+```js
+import { render, screen } from '@testing-library/react';
+import MyBlock from '../edit';
+
+describe('MyBlock', () => {
+  it('renders the block content', () => {
+    const attributes = { content: 'Hello World' };
+    render(<MyBlock attributes={attributes} />);
+    expect(screen.getByText('Hello World')).toBeInTheDocument();
+  });
+});
+```
+
+## Mocking WordPress globals
+
+Create `tests/js/setup-globals.js`:
+
+```js
+// Mock wp global
+global.wp = {
+  element: require('@wordpress/element'),
+  data: require('@wordpress/data'),
+  i18n: { __: (str) => str, _n: (s, p, n) => (n === 1 ? s : p) },
+};
+
+// Mock jQuery if needed
+global.jQuery = jest.fn(() => ({
+  on: jest.fn(),
+  off: jest.fn(),
+  trigger: jest.fn(),
+  ready: jest.fn((fn) => fn()),
+}));
+```
+
+Reference in `jest.config.js`:
+```js
+module.exports = {
+  ...require('@wordpress/scripts/config/jest-unit.config'),
+  setupFiles: ['./tests/js/setup-globals.js'],
+};
+```
+
+## Testing @wordpress/data stores
+
+```js
+import { createRegistry } from '@wordpress/data';
+import { store as myStore } from '../store';
+
+describe('My Store', () => {
+  let registry;
+
+  beforeEach(() => {
+    registry = createRegistry();
+    registry.register(myStore);
+  });
+
+  it('returns default state', () => {
+    const result = registry.select(myStore).getItems();
+    expect(result).toEqual([]);
+  });
+
+  it('adds an item via action', () => {
+    registry.dispatch(myStore).addItem({ id: 1, title: 'Test' });
+    const result = registry.select(myStore).getItems();
+    expect(result).toHaveLength(1);
+  });
+});
+```
+
+## Running
+
+```bash
+npx wp-scripts test-unit-js                  # Run all tests
+npx wp-scripts test-unit-js --watch          # Watch mode
+npx wp-scripts test-unit-js --coverage       # With coverage report
+npx wp-scripts test-unit-js -- path/to/test  # Run specific test
+```
+
+## Common issues
+
+- **"Cannot find module @wordpress/..."**: ensure the package is in dependencies; `@wordpress/scripts` provides many but not all
+- **JSX transform errors**: `@wordpress/scripts` handles this; don't add a separate Babel config unless needed
+- **Snapshot mismatches after update**: review changes, then `npx wp-scripts test-unit-js --updateSnapshot`

package/skills/wp-e2e-testing/references/phpunit-wordpress.md

@@ -0,0 +1,141 @@
+# PHPUnit for WordPress
+
+Use this file when writing or configuring PHPUnit tests for WordPress PHP code.
+
+## Scaffolding with WP-CLI
+
+```bash
+wp scaffold plugin-tests my-plugin
+```
+
+This creates:
+- `phpunit.xml.dist` — PHPUnit configuration
+- `tests/bootstrap.php` — WordPress test library loader
+- `tests/test-sample.php` — Example test
+- `bin/install-wp-tests.sh` — Script to install WP test library
+
+## Running with wp-env (recommended)
+
+wp-env includes the WordPress test suite out of the box:
+
+```bash
+npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin phpunit
+npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin phpunit -- --filter=test_activation
+```
+
+## Writing tests
+
+```php
+class Test_My_Plugin extends WP_UnitTestCase {
+
+    public function set_up(): void {
+        parent::set_up();
+        // Runs before each test
+    }
+
+    public function tear_down(): void {
+        // Runs after each test
+        parent::tear_down();
+    }
+
+    public function test_plugin_activates(): void {
+        $this->assertTrue( is_plugin_active( 'my-plugin/my-plugin.php' ) );
+    }
+
+    public function test_custom_post_type_registered(): void {
+        $this->assertTrue( post_type_exists( 'book' ) );
+    }
+
+    public function test_hook_fires(): void {
+        $fired = false;
+        add_action( 'my_plugin_init', function() use ( &$fired ) {
+            $fired = true;
+        });
+        do_action( 'my_plugin_init' );
+        $this->assertTrue( $fired );
+    }
+
+    public function test_filter_modifies_value(): void {
+        add_filter( 'my_plugin_title', function( $title ) {
+            return 'Modified: ' . $title;
+        });
+        $result = apply_filters( 'my_plugin_title', 'Original' );
+        $this->assertSame( 'Modified: Original', $result );
+    }
+}
+```
+
+## Testing REST API endpoints
+
+```php
+class Test_REST_API extends WP_UnitTestCase {
+
+    public function set_up(): void {
+        parent::set_up();
+        do_action( 'rest_api_init' );
+    }
+
+    public function test_endpoint_registered(): void {
+        $routes = rest_get_server()->get_routes();
+        $this->assertArrayHasKey( '/my-plugin/v1/items', $routes );
+    }
+
+    public function test_get_items(): void {
+        $request  = new WP_REST_Request( 'GET', '/my-plugin/v1/items' );
+        $response = rest_get_server()->dispatch( $request );
+        $this->assertSame( 200, $response->get_status() );
+    }
+
+    public function test_unauthorized_access(): void {
+        $request  = new WP_REST_Request( 'POST', '/my-plugin/v1/items' );
+        $response = rest_get_server()->dispatch( $request );
+        $this->assertSame( 401, $response->get_status() );
+    }
+}
+```
+
+## Test factories
+
+```php
+public function test_post_with_meta(): void {
+    $post_id = self::factory()->post->create([
+        'post_title'  => 'Test Post',
+        'post_status' => 'publish',
+    ]);
+    update_post_meta( $post_id, 'my_key', 'my_value' );
+
+    $this->assertSame( 'my_value', get_post_meta( $post_id, 'my_key', true ) );
+}
+
+public function test_user_with_role(): void {
+    $user_id = self::factory()->user->create([ 'role' => 'editor' ]);
+    wp_set_current_user( $user_id );
+
+    $this->assertTrue( current_user_can( 'edit_posts' ) );
+    $this->assertFalse( current_user_can( 'manage_options' ) );
+}
+```
+
+## phpunit.xml.dist configuration
+
+```xml
+<phpunit bootstrap="tests/bootstrap.php" colors="true">
+    <testsuites>
+        <testsuite name="My Plugin">
+            <directory suffix=".php">./tests/</directory>
+        </testsuite>
+    </testsuites>
+    <coverage>
+        <include>
+            <directory suffix=".php">./includes/</directory>
+        </include>
+    </coverage>
+</phpunit>
+```
+
+## Common issues
+
+- **"Class WP_UnitTestCase not found"**: bootstrap not loading; use wp-env or re-run `bin/install-wp-tests.sh`
+- **"No tests executed"**: test methods must start with `test_`; class must extend `WP_UnitTestCase`
+- **Database errors**: each test runs in a transaction that rolls back; avoid `dbDelta()` in tests
+- **`set_up()` not `setUp()`**: WordPress renamed the method in WP 5.9 for snake_case consistency

package/skills/wp-e2e-testing/references/playwright-wordpress.md

@@ -0,0 +1,108 @@
+# Playwright for WordPress E2E Testing
+
+Use this file when writing or configuring Playwright E2E tests for WordPress projects.
+
+## Installation
+
+```bash
+npm install -D @playwright/test @wordpress/e2e-test-utils-playwright
+npx playwright install chromium
+```
+
+## Configuration (`playwright.config.ts`)
+
+```ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  outputDir: './tests/e2e/artifacts',
+  fullyParallel: false, // WordPress state can conflict in parallel
+  retries: process.env.CI ? 2 : 0,
+  use: {
+    baseURL: process.env.WP_BASE_URL || 'http://localhost:8888',
+    storageState: process.env.STORAGE_STATE_PATH,
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+  },
+  webServer: {
+    command: 'npx wp-env start',
+    url: 'http://localhost:8888',
+    reuseExistingServer: true,
+    timeout: 120000,
+  },
+});
+```
+
+## WordPress-specific fixtures
+
+`@wordpress/e2e-test-utils-playwright` provides fixtures:
+
+```ts
+import { test, expect } from '@wordpress/e2e-test-utils-playwright';
+
+test('can create a post', async ({ admin, editor, page }) => {
+  await admin.visitAdminPage('post-new.php');
+  await editor.canvas.locator('[data-type="core/paragraph"]').click();
+  await page.keyboard.type('Hello from Playwright');
+  await editor.publishPost();
+  await expect(page.locator('.components-snackbar')).toContainText('published');
+});
+```
+
+Key fixtures:
+- `admin` — navigate to admin pages, authenticated as admin
+- `editor` — block editor helpers (canvas, inserter, publish)
+- `requestUtils` — REST API helpers for test data setup
+- `page` — standard Playwright page object
+
+## Authentication setup
+
+Create a global setup that stores auth state:
+
+```ts
+// tests/e2e/global-setup.ts
+import { request } from '@playwright/test';
+
+export default async function globalSetup() {
+  const api = await request.newContext({ baseURL: 'http://localhost:8888' });
+  await api.post('/wp-login.php', {
+    form: { log: 'admin', pwd: 'password', rememberme: 'forever' },
+  });
+  await api.storageState({ path: './tests/e2e/.auth/admin.json' });
+  await api.dispose();
+}
+```
+
+## Seeding test data via REST
+
+```ts
+test.beforeAll(async ({ requestUtils }) => {
+  await requestUtils.createPost({
+    title: 'Test Post',
+    content: '<!-- wp:paragraph --><p>Content</p><!-- /wp:paragraph -->',
+    status: 'publish',
+  });
+});
+
+test.afterAll(async ({ requestUtils }) => {
+  await requestUtils.deleteAllPosts();
+});
+```
+
+## Running tests
+
+```bash
+npx wp-scripts test-playwright              # Using @wordpress/scripts
+npx playwright test                          # Direct Playwright
+npx playwright test --ui                     # Interactive UI mode
+npx playwright test --grep "block editor"    # Filter by title
+```
+
+## Best practices
+
+- Use `test.describe.serial()` for tests that depend on order
+- Clean up test data in `afterAll` to prevent state leakage
+- Use `page.waitForLoadState('networkidle')` sparingly — prefer specific selectors
+- Store authentication state to avoid login in every test
+- Use `test.slow()` for tests involving complex editor operations

package/skills/wp-e2e-testing/references/test-data-generation.md

@@ -0,0 +1,127 @@
+# Test Data Generation
+
+Use this file when creating test data and fixtures for WordPress tests.
+
+## PHPUnit: WP test factories
+
+`WP_UnitTestCase` provides factory methods for creating test data:
+
+```php
+// Posts
+$post_id = self::factory()->post->create([
+    'post_title'  => 'Test Post',
+    'post_status' => 'publish',
+    'post_type'   => 'post',
+]);
+
+// Multiple posts
+$post_ids = self::factory()->post->create_many(10, [
+    'post_status' => 'publish',
+]);
+
+// Users
+$user_id = self::factory()->user->create([
+    'role'       => 'editor',
+    'user_login' => 'testeditor',
+]);
+
+// Terms
+$term_id = self::factory()->term->create([
+    'taxonomy' => 'category',
+    'name'     => 'Test Category',
+]);
+
+// Comments
+$comment_id = self::factory()->comment->create([
+    'comment_post_ID' => $post_id,
+    'comment_content'  => 'Test comment',
+]);
+
+// Attachments
+$attachment_id = self::factory()->attachment->create_upload_object(
+    DIR_TESTDATA . '/images/canola.jpg',
+    $post_id
+);
+```
+
+## Playwright E2E: requestUtils
+
+`@wordpress/e2e-test-utils-playwright` provides REST API-based data creation:
+
+```ts
+test.beforeAll(async ({ requestUtils }) => {
+    await requestUtils.createPost({
+        title: 'E2E Test Post',
+        content: '<!-- wp:paragraph --><p>Test content</p><!-- /wp:paragraph -->',
+        status: 'publish',
+    });
+
+    await requestUtils.createPage({
+        title: 'Test Page',
+        status: 'publish',
+    });
+});
+```
+
+## WP-CLI bulk data generation
+
+```bash
+# Generate posts
+npx wp-env run cli wp post generate --count=50 --post_type=post --post_status=publish
+
+# Generate users
+npx wp-env run cli wp user generate --count=10 --role=subscriber
+
+# Import theme unit test data (standard WP test content)
+npx wp-env run cli wp import /tmp/theme-unit-test-data.xml --authors=create
+```
+
+## Cleanup patterns
+
+### PHPUnit (automatic)
+
+Each PHPUnit test runs in a database transaction that rolls back automatically. Factory-created data is cleaned up without explicit teardown.
+
+### Playwright (manual cleanup)
+
+```ts
+test.afterAll(async ({ requestUtils }) => {
+    await requestUtils.deleteAllPosts();
+    await requestUtils.deleteAllPages();
+});
+```
+
+### Between test runs
+
+```bash
+npx wp-env clean all  # Reset both databases to initial state
+```
+
+## Fixtures for complex scenarios
+
+Create a reusable fixture file:
+
+```php
+// tests/fixtures/class-test-fixtures.php
+class Test_Fixtures {
+    public static function create_sample_store(): array {
+        $category = self::factory()->term->create(['taxonomy' => 'product_cat', 'name' => 'Widgets']);
+        $products = self::factory()->post->create_many(5, [
+            'post_type'   => 'product',
+            'post_status' => 'publish',
+        ]);
+        foreach ($products as $id) {
+            wp_set_object_terms($id, $category, 'product_cat');
+        }
+        return compact('category', 'products');
+    }
+}
+```
+
+## Best practices
+
+- Create the minimum data needed for each test
+- Use factories over raw SQL or direct `wp_insert_post()` calls
+- Name test data clearly to distinguish from real content
+- Clean up E2E test data in `afterAll` hooks
+- Avoid relying on auto-increment IDs; query by known attributes