Skip to main content

Playwright Integration Guide

Overview​

DocuMCP can generate a complete Playwright E2E testing setup for your documentation site, including:

  • Playwright configuration
  • Link validation tests
  • Accessibility tests (WCAG 2.1 AA)
  • Docker/Podman containerization
  • GitHub Actions CI/CD workflow

Important: Playwright is NOT a dependency of DocuMCP itself. Instead, DocuMCP generates the Playwright setup for your documentation site.

Quick Start​

Generate Playwright Setup​

Use the setup_playwright_tests tool to generate all necessary files:

{
  tool: "setup_playwright_tests",
  arguments: {
    repositoryPath: "./my-docs-site",
    ssg: "docusaurus",
    projectName: "My Documentation",
    mainBranch: "main",
    includeAccessibilityTests: true,
    includeDockerfile: true,
    includeGitHubActions: true
  }
}

What Gets Generated​

my-docs-site/
├── playwright.config.ts           # Playwright configuration
├── Dockerfile.playwright           # Multi-stage Docker build
├── .github/workflows/
│   └── docs-e2e-tests.yml         # CI/CD workflow
├── tests/e2e/
│   ├── link-validation.spec.ts    # Link tests
│   └── accessibility.spec.ts       # A11y tests
├── package.json                    # Updated with Playwright deps
└── .gitignore                     # Updated with test artifacts

Generated Files Explained​

1. Playwright Config (playwright.config.ts)​

export default defineConfig({
  testDir: "./tests/e2e",
  timeout: 30 * 1000,
  use: {
    baseURL: process.env.BASE_URL || "http://localhost:3000",
  },
  projects: [{ name: "chromium" }, { name: "firefox" }, { name: "webkit" }],
});
  • ✅ Internal navigation links
  • ✅ External link HTTP status
  • ✅ Anchor/hash links
  • ✅ 404 detection

3. Accessibility Tests​

  • ✅ WCAG 2.1 AA compliance (axe-core)
  • ✅ Keyboard navigation
  • ✅ Image alt text
  • ✅ Color contrast

4. Docker Multi-Stage Build​

# Build docs
FROM node:20-alpine AS builder
RUN npm run build

# Run tests
FROM mcr.microsoft.com/playwright:v1.55.1 AS tester
RUN npx playwright test

# Serve production
FROM nginx:alpine AS server
COPY build /usr/share/nginx/html

5. GitHub Actions Workflow​

Automated testing on every push/PR:

  1. Build → Compile documentation
  2. Test → Run Playwright in container (chromium, firefox, webkit)
  3. Deploy → Push to GitHub Pages (if tests pass)
  4. Verify → Test live production site

Usage After Generation​

Local Testing​

# Install dependencies (in YOUR docs site, not DocuMCP)
cd my-docs-site
npm install

# Install Playwright browsers
npx playwright install

# Run tests
npm run test:e2e

# Run tests in UI mode
npm run test:e2e:ui

# View test report
npm run test:e2e:report

Docker Testing​

# Build test container
docker build -t my-docs-test -f Dockerfile.playwright .

# Run tests in container
docker run --rm my-docs-test

# Or with Podman
podman build -t my-docs-test -f Dockerfile.playwright .
podman run --rm my-docs-test

CI/CD Integration​

Push to trigger GitHub Actions:

git add .
git commit -m "Add Playwright E2E tests"
git push origin main

Workflow will automatically:

  • Build docs
  • Run E2E tests across browsers
  • Deploy to GitHub Pages (if all tests pass)
  • Test production site after deployment

Customization​

Add More Tests​

Create new test files in tests/e2e/:

// tests/e2e/navigation.spec.ts
import { test, expect } from "@playwright/test";

test("breadcrumbs should work", async ({ page }) => {
  await page.goto("/docs/some-page");
  const breadcrumbs = page.locator('[aria-label="breadcrumb"]');
  await expect(breadcrumbs).toBeVisible();
});

Modify Configuration​

Edit playwright.config.ts:

export default defineConfig({
  // Increase timeout for slow networks
  timeout: 60 * 1000,

  // Add mobile viewports
  projects: [
    { name: "chromium" },
    { name: "Mobile Chrome", use: devices["Pixel 5"] },
  ],
});

SSG-Specific Configuration​

DocuMCP automatically configures for your SSG:

SSGBuild CommandBuild DirPort
Jekyllbundle exec jekyll build_site4000
Hugohugopublic1313
Docusaurusnpm run buildbuild3000
MkDocsmkdocs buildsite8000
Eleventynpx @11ty/eleventy_site8080

Knowledge Graph Integration​

Test results are tracked in DocuMCP's Knowledge Graph:

{
  type: "deployment_validation",
  properties: {
    playwrightResults: {
      totalTests: 25,
      passed: 24,
      failed: 1,
      browsers: ["chromium", "firefox", "webkit"],
      linksChecked: 127,
      brokenLinks: 0,
      accessibilityScore: 98,
    }
  }
}

Troubleshooting​

External link validation can fail due to:

  • Network timeouts
  • Rate limiting
  • CORS issues

Solution: Tests only check first 10 external links. Increase timeout in config.

Container Build Fails​

Issue: Docker build fails on dependency installation

Solution: Check SSG-specific dependencies in package.json

CI/CD Workflow Times Out​

Issue: GitHub Actions workflow exceeds time limit

Solution: Run only chromium in CI, full matrix locally:

# .github/workflows/docs-e2e-tests.yml
strategy:
  matrix:
    browser: [chromium] # Only chromium in CI

Best Practices​

  1. Run tests before pushing - npm run test:e2e
  2. Use Docker locally - Same environment as CI
  3. Update baselines - When changing UI intentionally
  4. Monitor CI reports - Check artifacts for failures
  5. Test production - Workflow tests live site automatically

Example Workflow​

# 1. User analyzes their documentation repo with DocuMCP
documcp analyze_repository --path ./my-docs

# 2. User generates Playwright setup
documcp setup_playwright_tests \
  --repositoryPath ./my-docs \
  --ssg docusaurus \
  --projectName "My Docs"

# 3. User installs dependencies (in THEIR repo)
cd my-docs
npm install
npx playwright install

# 4. User runs tests locally
npm run test:e2e

# 5. User pushes to GitHub
git push origin main

# 6. GitHub Actions runs tests automatically
# 7. If tests pass, deploys to GitHub Pages
# 8. Tests production site

Resources​