web-tests

What this skill does

**IMPORTANT - Path Resolution:**
This skill is installed globally but saves outputs to the user's working directory. Always pass `CWD` environment variable when executing commands to ensure outputs go to the correct location.

Common installation paths:

- Plugin system: `~/.claude/plugins/marketplaces/claude-craftkit/plugins/ui-tests/skills/web-tests`
- Manual global: `~/.claude/skills/web-tests`
- Project-specific: `<project>/.claude/skills/web-tests`

# Web Testing & Browser Automation

General-purpose browser automation skill. I'll write custom Playwright code for any automation task you request and execute it via the universal executor.

**CRITICAL WORKFLOW - Follow these steps in order:**

1. **Auto-detect dev servers** - For localhost testing, ALWAYS run server detection FIRST:

   ```bash
   cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))"
   ```

   - If **1 server found**: Use it automatically, inform user
   - If **multiple servers found**: Ask user which one to test
   - If **no servers found**: Ask for URL or offer to help start dev server

2. **Write scripts to user's working directory** - Save to `.web-tests/scripts/test-*.js` in user's repo

3. **Use visible browser by default** - Always use `headless: false` unless user specifically requests headless mode

4. **Parameterize URLs** - Always make URLs configurable via constant at top of script

## How It Works

1. You describe what you want to test/automate
2. I auto-detect running dev servers (or ask for URL if testing external site)
3. I write custom Playwright code in `.web-tests/scripts/test-*.js` (in user's working directory)
4. I execute it via: `CWD=$(pwd) cd $SKILL_DIR && node run.js .web-tests/scripts/test-*.js`
5. Results displayed in real-time, browser window visible for debugging
6. Screenshots automatically saved to `.web-tests/screenshots/`

## Setup (First Time)

```bash
cd $SKILL_DIR
npm run setup
```

This installs Playwright and Chromium browser. Only needed once.

## Execution Pattern

**Step 1: Detect dev servers (for localhost testing)**

```bash
cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(s => console.log(JSON.stringify(s)))"
```

**Step 2: Write test script to user's .web-tests/scripts/ with URL parameter**

```javascript
// .web-tests/scripts/test-page.js
const { chromium } = require("playwright");

// Parameterized URL (detected or user-provided)
const TARGET_URL = "http://localhost:3001"; // <-- Auto-detected or from user

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(TARGET_URL);
  console.log("Page loaded:", await page.title());

  await page.screenshot({
    path: ".web-tests/screenshots/page.png",
    fullPage: true,
  });
  console.log("📸 Screenshot saved to .web-tests/screenshots/page.png");

  await browser.close();
})();
```

**Step 3: Execute from skill directory with CWD**

```bash
CWD=$(pwd) cd $SKILL_DIR && node run.js $(pwd)/.web-tests/scripts/test-page.js
```

## Common Patterns

### Test a Page (Multiple Viewports)

```javascript
// .web-tests/scripts/test-responsive.js
const { chromium } = require("playwright");
const helpers = require("$SKILL_DIR/lib/helpers"); // Path will be resolved

const TARGET_URL = "http://localhost:3001"; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();

  // Desktop test
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.goto(TARGET_URL);
  console.log("Desktop - Title:", await page.title());
  await helpers.takeScreenshot(page, "desktop"); // Saves to .web-tests/screenshots/

  // Mobile test
  await page.setViewportSize({ width: 375, height: 667 });
  await helpers.takeScreenshot(page, "mobile");

  await browser.close();
})();
```

### Test Login Flow

```javascript
// .web-tests/scripts/test-login.js
const { chromium } = require("playwright");

const TARGET_URL = "http://localhost:3001"; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/login`);

  await page.fill('input[name="email"]', "[email protected]");
  await page.fill('input[name="password"]', "password123");
  await page.click('button[type="submit"]');

  // Wait for redirect
  await page.waitForURL("**/dashboard");
  console.log("✅ Login successful, redirected to dashboard");

  await browser.close();
})();
```

### Fill and Submit Form

```javascript
// .web-tests/scripts/test-form.js
const { chromium } = require("playwright");
const helpers = require("$SKILL_DIR/lib/helpers");

const TARGET_URL = "http://localhost:3001"; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 50 });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/contact`);

  await page.fill('input[name="name"]', "John Doe");
  await page.fill('input[name="email"]', "[email protected]");
  await page.fill('textarea[name="message"]', "Test message");

  await helpers.takeScreenshot(page, "form-filled");
  await page.click('button[type="submit"]');

  // Verify submission
  await page.waitForSelector(".success-message");
  console.log("✅ Form submitted successfully");
  await helpers.takeScreenshot(page, "form-success");

  await browser.close();
})();
```

### Check for Broken Links

```javascript
// .web-tests/scripts/test-broken-links.js
const { chromium } = require("playwright");

const TARGET_URL = "http://localhost:3001";

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(TARGET_URL);

  const links = await page.locator('a[href^="http"]').all();
  const results = { working: 0, broken: [] };

  for (const link of links) {
    const href = await link.getAttribute("href");
    try {
      const response = await page.request.head(href);
      if (response.ok()) {
        results.working++;
      } else {
        results.broken.push({ url: href, status: response.status() });
      }
    } catch (e) {
      results.broken.push({ url: href, error: e.message });
    }
  }

  console.log(`✅ Working links: ${results.working}`);
  console.log(`❌ Broken links:`, results.broken);

  await browser.close();
})();
```

### Take Screenshot with Error Handling

```javascript
// .web-tests/scripts/screenshot-with-error-handling.js
const { chromium } = require("playwright");
const helpers = require("$SKILL_DIR/lib/helpers");

const TARGET_URL = "http://localhost:3001";

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  try {
    await page.goto(TARGET_URL, {
      waitUntil: "networkidle",
      timeout: 10000,
    });

    await helpers.takeScreenshot(page, "page-success");
    console.log("📸 Screenshot saved successfully");
  } catch (error) {
    console.error("❌ Error:", error.message);
    await helpers.takeScreenshot(page, "page-error");
  } finally {
    await browser.close();
  }
})();
```

### Test Responsive Design (Full)

```javascript
// .web-tests/scripts/test-responsive-full.js
const { chromium } = require("playwright");
const helpers = require("$SKILL_DIR/lib/helpers");

const TARGET_URL = "http://localhost:3001"; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  const viewports = [
    { name: "Desktop", width: 1920, height: 1080 },
    { name: "Tablet", width: 768, height: 1024 },
    { name: "Mobile", width: 375, height: 667 },
  ];

  for (const viewport of viewports) {
    console.log(
      `Testing ${viewport.name} (${viewport.width}x${viewport.height})`
    );

    await page.setViewportSize({
      width: viewport.width,
      height: v