claude-plugin-wordpress-manager 1.5.0 → 1.7.1

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

package/skills/wp-e2e-testing/references/visual-regression.md

@@ -0,0 +1,107 @@
+# Visual Regression Testing
+
+Use this file when adding screenshot-based visual regression tests to a WordPress project.
+
+## Playwright built-in approach (recommended)
+
+Playwright includes `toHaveScreenshot()` for visual comparison:
+
+```ts
+import { test, expect } from '@wordpress/e2e-test-utils-playwright';
+
+test('homepage matches visual baseline', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveScreenshot('homepage.png', {
+    maxDiffPixelRatio: 0.01, // Allow 1% pixel difference
+  });
+});
+
+test('block renders correctly in editor', async ({ admin, editor, page }) => {
+  await admin.visitAdminPage('post-new.php');
+  await editor.insertBlock({ name: 'my-plugin/my-block' });
+  const block = editor.canvas.locator('[data-type="my-plugin/my-block"]');
+  await expect(block).toHaveScreenshot('my-block-editor.png');
+});
+```
+
+## Generating baselines
+
+```bash
+# First run: creates baseline screenshots
+npx playwright test --update-snapshots
+
+# Subsequent runs: compare against baselines
+npx playwright test
+```
+
+Baselines are stored in `tests/e2e/__snapshots__/` by default.
+
+## Handling dynamic content
+
+Mask elements that change between runs:
+
+```ts
+await expect(page).toHaveScreenshot('dashboard.png', {
+  mask: [
+    page.locator('.current-time'),
+    page.locator('.random-ad'),
+    page.locator('#wpadminbar'), // Admin bar may show user-specific data
+  ],
+});
+```
+
+## Disable animations
+
+Add to `playwright.config.ts` to prevent animation-related flakiness:
+
+```ts
+use: {
+  // ...
+  contextOptions: {
+    reducedMotion: 'reduce',
+  },
+},
+```
+
+## Consistent viewport
+
+```ts
+use: {
+  viewport: { width: 1280, height: 720 },
+},
+```
+
+## CI integration
+
+Playwright stores screenshots as test artifacts. In GitHub Actions:
+
+```yaml
+- uses: actions/upload-artifact@v4
+  if: failure()
+  with:
+    name: visual-regression-diffs
+    path: tests/e2e/artifacts/
+    retention-days: 7
+```
+
+## Updating baselines after intentional changes
+
+```bash
+npx playwright test --update-snapshots
+git add tests/e2e/__snapshots__/
+git commit -m "Update visual regression baselines"
+```
+
+## Threshold tuning
+
+- `maxDiffPixelRatio: 0.01` — 1% tolerance (good default)
+- `maxDiffPixels: 100` — absolute pixel count tolerance
+- `threshold: 0.2` — per-pixel color sensitivity (0-1, lower = stricter)
+
+Use higher thresholds for pages with web fonts (rendering varies across OS).
+
+## Common issues
+
+- **False positives on CI**: OS font rendering differs; consider running in Docker or using consistent font stacks
+- **Flaky screenshots**: add `await page.waitForLoadState('networkidle')` before screenshots; mask dynamic elements
+- **Large snapshot files**: use PNG compression; store in Git LFS for large projects

package/skills/wp-e2e-testing/references/wp-env-setup.md

@@ -0,0 +1,97 @@
+# wp-env Test Environment Setup
+
+Use this file when setting up or configuring wp-env as a test environment for WordPress development.
+
+## Minimal `.wp-env.json` for testing
+
+```json
+{
+  "core": null,
+  "phpVersion": "8.2",
+  "plugins": ["./"],
+  "config": {
+    "WP_DEBUG": true,
+    "SCRIPT_DEBUG": true
+  },
+  "port": 8888,
+  "testsPort": 8889
+}
+```
+
+For a theme project, replace `"plugins": ["./"]` with `"themes": ["./"]`.
+
+## Starting and managing
+
+```bash
+npx wp-env start              # Start both dev and test environments
+npx wp-env start --update     # Start and pull latest images
+npx wp-env stop               # Stop containers (preserves data)
+npx wp-env destroy             # Remove containers and data
+npx wp-env clean all           # Reset databases only
+```
+
+## Running commands inside wp-env
+
+```bash
+# WP-CLI in development environment
+npx wp-env run cli wp plugin list
+
+# WP-CLI in tests environment
+npx wp-env run tests-cli wp option get siteurl
+
+# PHPUnit in tests container
+npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin phpunit
+
+# Arbitrary bash
+npx wp-env run cli bash -c "cat wp-config.php | grep WP_DEBUG"
+```
+
+## Default credentials
+
+- **Development**: `http://localhost:8888` — admin / password
+- **Tests**: `http://localhost:8889` — admin / password
+
+## Custom PHP and WP versions
+
+```json
+{
+  "core": "WordPress/WordPress#6.8",
+  "phpVersion": "8.1"
+}
+```
+
+This is useful for testing compatibility matrices. Each CI job can override these values.
+
+## Mounting additional plugins/themes
+
+```json
+{
+  "plugins": [
+    "./",
+    "https://downloads.wordpress.org/plugin/gutenberg.latest-stable.zip"
+  ],
+  "mappings": {
+    "wp-content/mu-plugins": "./test-utils/mu-plugins"
+  }
+}
+```
+
+## Override file for local settings
+
+Create `.wp-env.override.json` (gitignored) for developer-specific settings:
+
+```json
+{
+  "port": 9999,
+  "config": {
+    "WP_DEBUG_LOG": true
+  }
+}
+```
+
+## Common issues
+
+- **Port conflict**: change `port`/`testsPort` or stop the conflicting service
+- **Docker not running**: `docker info` must succeed; start Docker Desktop or daemon
+- **Stale containers**: `npx wp-env destroy && npx wp-env start` for a clean slate
+- **Plugin not activated**: run `npx wp-env run cli wp plugin activate my-plugin`