Testing Testing

Testing Guide - DesignSetGo

This document covers the end-to-end (E2E) testing setup for the DesignSetGo WordPress plugin using Playwright.

Table of Contents

• Overview
• Installation
• Running Tests
• Test Structure
• Writing Tests
• MCP Integration
• Troubleshooting

Overview

DesignSetGo uses Playwright for end-to-end testing. Playwright provides:

• Cross-browser testing: Chromium, Firefox, WebKit (Safari)
• Mobile testing: Emulated mobile devices
• Auto-wait: Automatically waits for elements to be ready
• Network control: Mock APIs, intercept requests
• Screenshots & videos: Automatic debugging artifacts
• Parallel execution: Fast test runs

What We Test

• Block enhancements: Responsive grid, visibility, overlays
• Editor interactions: Block insertion, settings, controls
• Frontend rendering: Verify correct HTML/CSS output
• Responsive behavior: Different viewport sizes
• WordPress integration: Compatibility with core blocks

Installation

1. Install Dependencies

npm install

This installs Playwright and all dependencies listed in package.json.

2. Install Playwright Browsers

npm run test:install

This downloads Chromium, Firefox, and WebKit browsers (~400MB).

3. Start WordPress Environment

npm run wp-env:start

This starts a local WordPress instance using wp-env (Docker).

WordPress will be available at:

• Frontend: http://localhost:8888
• Admin: http://localhost:8888/wp-admin
• Credentials: admin / password

Running Tests

Basic Commands

# Run all tests (headless)
npm run test:e2e

# Run with UI mode (interactive)
npm run test:e2e:ui

# Run with browser visible
npm run test:e2e:headed

# Debug mode (step through tests)
npm run test:e2e:debug

Browser-Specific Tests

# Chrome only
npm run test:e2e:chromium

# Firefox only
npm run test:e2e:firefox

# Safari only
npm run test:e2e:webkit

# Mobile devices
npm run test:e2e:mobile

View Test Reports

# After test run, open HTML report
npm run test:e2e:report

Running Specific Tests

# Run a single test file
npx playwright test tests/e2e/group-enhancements.spec.js

# Run tests matching a pattern
npx playwright test --grep "responsive grid"

# Run a specific test by line number
npx playwright test tests/e2e/group-enhancements.spec.js:15

Test Structure

Directory Layout

tests/
├── e2e/
│   ├── auth.setup.js              ← Authentication setup
│   ├── cleanup.teardown.js        ← Cleanup after tests
│   ├── group-enhancements.spec.js ← Group block tests
│   └── helpers/
│       └── wordpress.js           ← Helper functions
├── unit/                          ← Unit tests (Jest)
└── phpunit/                       ← PHP unit tests

Test Files

• *.setup.js: Setup scripts (authentication, database seeding)
• *.spec.js: Test files
• *.teardown.js: Cleanup scripts
• helpers/: Shared utility functions

Configuration

• playwright.config.js: Main Playwright configuration
• .claude/mcp.json: MCP server configuration for Claude integration

Writing Tests

Basic Test Structure

const { test, expect } = require('@playwright/test');
const { createNewPost, insertBlock, selectBlock } = require('./helpers/wordpress');

test.describe('My Feature', () => {
  test('should do something', async ({ page }) => {
    // Arrange
    await createNewPost(page, 'post');
    await insertBlock(page, 'core/group');

    // Act
    await selectBlock(page, 'core/group');
    await page.click('button[aria-label="Settings"]');

    // Assert
    await expect(page.locator('.my-control')).toBeVisible();
  });
});

Available Helper Functions

createNewPost(page, postType)

Creates a new post or page in the block editor.

await createNewPost(page, 'post'); // or 'page'

insertBlock(page, blockName)

Inserts a block by name.

await insertBlock(page, 'core/group');
await insertBlock(page, 'core/paragraph');

selectBlock(page, blockType, index)

Selects a block by type and optional index.

await selectBlock(page, 'core/group', 0);

openBlockSettings(page)

Opens the block settings sidebar.

await openBlockSettings(page);

savePost(page)

Saves the current post.

await savePost(page);

publishPost(page)

Publishes the current post.

await publishPost(page);

blockHasClass(page, blockType, className, index)

Checks if a block has a specific CSS class.

const hasClass = await blockHasClass(page, 'core/group', 'dsgo-grid-cols-3');
expect(hasClass).toBeTruthy();

Testing Responsive Behavior

test('should hide on mobile', async ({ page, context }) => {
  // Desktop test
  await page.goto(postUrl);
  await expect(page.locator('.my-element')).toBeVisible();

  // Mobile test
  const mobilePage = await context.newPage();
  await mobilePage.setViewportSize({ width: 375, height: 667 });
  await mobilePage.goto(postUrl);
  await expect(mobilePage.locator('.my-element')).toBeHidden();
});

Testing Frontend Output

test('should render correctly on frontend', async ({ page }) => {
  // Create and publish post
  await createNewPost(page);
  await insertBlock(page, 'core/group');
  await publishPost(page);

  // Get frontend URL
  const previewUrl = await page.locator('.edit-post-header-preview__button-external').getAttribute('href');

  // Visit frontend
  await page.goto(previewUrl);

  // Verify frontend rendering
  const group = page.locator('.wp-block-group.dsgo-grid-cols-3');
  await expect(group).toBeVisible();
});

Debugging Tips

1. Use page.pause()

Pauses test execution and opens Playwright Inspector.

await page.pause(); // Test stops here

2. Take Screenshots

await page.screenshot({ path: 'debug.png' });

3. Console Logs

page.on('console', msg => console.log(msg.text()));

4. Slow Down Execution

test.use({ slowMo: 1000 }); // Delay 1 second between actions

MCP Integration

MCP (Model Context Protocol) allows Claude Code to interact with Playwright for automated testing and debugging.

Configuration

The MCP server is configured in .claude/mcp.json:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"],
      "env": {
        "PLAYWRIGHT_CONFIG": "playwright.config.js",
        "PLAYWRIGHT_BASE_URL": "http://localhost:8888"
      }
    }
  }
}

Using MCP with Claude

Once configured, Claude can:

• Run Playwright tests
• Generate test code
• Debug test failures
• Analyze test results
• Suggest test improvements

Example prompts:

• "Run the group enhancements tests"
• "Debug the failing responsive grid test"
• "Create a test for the new overlay feature"
• "Show me the test coverage report"

Troubleshooting

WordPress Not Starting

Problem: webServer timeout error.

Solution:

# Stop and clean wp-env
npm run wp-env:stop
npm run wp-env:clean

# Start fresh
npm run wp-env:start

Authentication Failing

Problem: Tests fail at login step.

Solution:

1. Check WordPress is running: http://localhost:8888
2. Verify credentials in tests/e2e/auth.setup.js
3. Delete old storage state: rm -rf artifacts/storage-states
4. Re-run setup: npx playwright test --project=setup

Browsers Not Installed

Problem: browserType.launch: Executable doesn't exist

Solution:

npm run test:install

Port Conflicts

Problem: Port 8888 already in use.

Solution:

# Option 1: Stop wp-env
npm run wp-env:stop

# Option 2: Use different port
export WP_BASE_URL=http://localhost:8889
npm run wp-env:start
npm run test:e2e

Tests Timing Out

Problem: Test timeout of 60000ms exceeded

Solution:

1. Increase timeout in playwright.config.js:

   timeout: 120000, // 2 minutes

2. Use test.slow() for specific tests:

   test.slow(); // 3x timeout for this test

Flaky Tests

Problem: Tests pass/fail randomly.

Solution:

1. Add explicit waits:

   await page.waitForSelector('.my-element');
   await page.waitForLoadState('networkidle');

2. Use auto-wait assertions:

   await expect(page.locator('.my-element')).toBeVisible();

3. Enable retries in config:

   retries: 2,

Debug Mode Not Working

Problem: --debug flag doesn't stop at breakpoints.

Solution:

1. Use await page.pause() in test code
2. Run with UI mode instead: npm run test:e2e:ui

Best Practices

1. Use Page Objects

Create reusable page objects for common workflows:

class EditorPage {
  constructor(page) {
    this.page = page;
  }

  async openSettings() {
    await this.page.click('button[aria-label="Settings"]');
  }

  async setGridColumns(desktop, tablet, mobile) {
    await this.openSettings();
    // ... implementation
  }
}

2. Keep Tests Independent

Each test should be able to run in isolation:

test.beforeEach(async ({ page }) => {
  await createNewPost(page);
});

3. Use Descriptive Names

// ✅ Good
test('should hide group on mobile when responsive visibility is enabled', ...)

// ❌ Bad
test('test1', ...)

4. Test User Flows, Not Implementation

// ✅ Good - Tests user behavior
test('user can create a 3-column grid', async ({ page }) => {
  await insertBlock(page, 'core/group');
  await setGridLayout(page, 3);
  await expect(page.locator('.grid-cols-3')).toBeVisible();
});

// ❌ Bad - Tests implementation details
test('dsgGridColumns attribute is set', ...)

5. Clean Up After Tests

test.afterEach(async ({ page }) => {
  // Delete test posts, reset state, etc.
});

Continuous Integration

GitHub Actions Example

name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run test:install
      - run: npm run test:e2e
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

Resources

• Playwright Documentation
• WordPress Block Editor Handbook
• wp-env Documentation
• Best Practices for E2E Testing

Getting Help

• Playwright Issues: https://github.com/microsoft/playwright/issues
• WordPress Testing: https://make.wordpress.org/core/handbook/testing/
• DesignSetGo Issues: [Project issue tracker]

---

Last Updated: 2025-10-24 Playwright Version: 1.56.1 WordPress Compatibility: 6.4+

---

Auto-generated from docs/testing/TESTING.md. To update, edit the source file and changes will sync on next push to main.