verify-web-change

What this skill does

# Verify Web Change

Verify that pull request changes work correctly in a running web application using browser automation.

## Critical Requirements

**Playwright MCP is MANDATORY.** This skill cannot function without it.

## Workflow

Execute these steps in order. Do not skip steps.

### Step 1: Verify Playwright MCP Availability

**MUST exit if this step fails.**

Test Playwright MCP by attempting to list browser tabs:

```
mcp__playwright__browser_tabs
  action: "list"
```

If this tool:
- **Succeeds**: Continue to Step 2
- **Fails with "tool not found"**: EXIT immediately with message:
  ```
  ❌ VERIFICATION FAILED: Playwright MCP server is not installed.

  To install:
  1. Run: npx @anthropic-ai/mcp-server-playwright
  2. Configure in Claude Code MCP settings
  3. Restart Claude Code
  ```
- **Fails with connection error**: EXIT with message about MCP server not running

**Do NOT proceed if Playwright MCP is unavailable.**

### Step 2: Analyze PR Changes

Before launching the application, understand what to verify.

#### 2.1 Get Changed Files

```bash
git diff main --name-only
git diff main --stat
```

#### 2.2 Understand the Changes (ULTRATHINK)

Read the changed files and related context to understand:
- What UI elements were added/modified?
- What user interactions should work?
- What visual changes should be visible?
- Are there related test files that show expected behavior?

```bash
# Check for existing Playwright/E2E tests
find . -name "*.spec.ts" -o -name "*.test.ts" -o -name "*.e2e.ts" | head -20
ls -la tests/ e2e/ playwright/ __tests__/ 2>/dev/null || true
```

If Playwright tests exist, read them to understand:
- What pages/routes are tested
- What elements are interacted with
- What assertions are made

#### 2.3 Define Verification Criteria

Create a mental checklist of what must be verified:
- [ ] Specific UI element(s) present
- [ ] Specific interaction(s) work
- [ ] No console errors
- [ ] Expected visual appearance

### Step 3: Ensure Docker is Running (if needed)

Before launching any services, check if the project needs Docker and ensure the daemon is running.

#### 3.1 Check for Compose Files

```bash
COMPOSE_FILE=""
for f in docker-compose.yml docker-compose.yaml compose.yml compose.yaml; do
    if [[ -f "$f" ]]; then
        COMPOSE_FILE="$f"
        break
    fi
done
echo "Compose file: ${COMPOSE_FILE:-none}"
```

If no compose file is found, skip to Step 4.

#### 3.2 Verify Docker Daemon is Running

```bash
docker info > /dev/null 2>&1
```

If this fails, the Docker daemon is not running. Try to start it:

```bash
# Check current status
service docker status 2>/dev/null || systemctl status docker 2>/dev/null || true
```

If the daemon is stopped, start it:

```bash
# Try without sudo first
service docker start 2>/dev/null \
  || systemctl start docker 2>/dev/null \
  || sudo service docker start 2>/dev/null \
  || sudo systemctl start docker 2>/dev/null
```

**Wait for Docker to be ready after starting:**

```bash
for i in $(seq 1 10); do
    docker info > /dev/null 2>&1 && break
    echo "Waiting for Docker daemon... ($i/10)"
    sleep 2
done

# Final check
if ! docker info > /dev/null 2>&1; then
    echo "❌ Docker daemon failed to start. Start it manually and retry."
    echo "   Try: sudo systemctl start docker"
    echo "   Or:  sudo service docker start"
    # Continue without Docker — the app may still work without services
fi
```

#### 3.3 Start Compose Services

```bash
# Prefer `docker compose` (v2 plugin) over `docker-compose` (standalone)
if docker compose version > /dev/null 2>&1; then
    docker compose up -d
else
    docker-compose up -d
fi
```

**Wait for services to be healthy** — don't just sleep:

```bash
# If compose services define healthchecks, wait for them
if docker compose version > /dev/null 2>&1; then
    # Check if any services have healthchecks
    if docker compose ps --format json 2>/dev/null | grep -q '"Health"'; then
        echo "Waiting for healthy services..."
        for i in $(seq 1 30); do
            UNHEALTHY=$(docker compose ps --format json 2>/dev/null | grep -c '"starting"\|"unhealthy"' || true)
            if [[ "$UNHEALTHY" -eq 0 ]]; then
                echo "All services healthy."
                break
            fi
            echo "  Waiting for $UNHEALTHY service(s)... ($i/30)"
            sleep 2
        done
    else
        # No healthchecks — fall back to a brief wait
        echo "No healthchecks defined. Waiting 5s for services..."
        sleep 5
    fi
fi
```

#### 3.4 Verify Key Services

After compose services start, check that critical ports are actually listening:

```bash
# Common service ports — check whatever the compose file exposes
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}" 2>/dev/null || docker-compose ps
```

If a database or API service failed to start, report it and decide whether to continue.

### Step 4: Launch Application Stack

#### 4.1 Detect Package Manager

```bash
if [[ -f "bun.lockb" ]] || [[ -f "bun.lock" ]]; then
    PM="bun"
elif [[ -f "pnpm-lock.yaml" ]]; then
    PM="pnpm"
elif [[ -f "yarn.lock" ]]; then
    PM="yarn"
else
    PM="npm"
fi
echo "Package manager: $PM"
```

#### 4.2 Check for Environment Files

Many apps won't start without environment configuration:

```bash
# Check for env templates that need to be copied
for tmpl in .env.example .env.template .env.sample; do
    if [[ -f "$tmpl" ]] && [[ ! -f ".env" ]] && [[ ! -f ".env.local" ]]; then
        echo "⚠️  Found $tmpl but no .env or .env.local — copying $tmpl to .env"
        cp "$tmpl" .env
        break
    fi
done

# Check if required env files exist
if [[ -f ".env.local" ]] || [[ -f ".env" ]] || [[ -f ".env.development" ]]; then
    echo "Environment file found."
else
    echo "⚠️  No .env file detected. App may fail if it requires environment variables."
fi
```

#### 4.3 Install Dependencies (if needed)

```bash
[[ -d "node_modules" ]] || $PM install
```

#### 4.4 Detect Dev Server Port

Detect the port BEFORE starting the server so we know where to navigate:

```bash
PORT=""

# 1. Check vite.config.ts / vite.config.js (most common for bun/vite stacks)
for cfg in vite.config.ts vite.config.js vite.config.mts; do
    if [[ -f "$cfg" ]]; then
        # Look for server.port or preview.port
        VITE_PORT=$(grep -oP 'port\s*:\s*\K\d+' "$cfg" | head -1)
        if [[ -n "$VITE_PORT" ]]; then
            PORT="$VITE_PORT"
            echo "Port $PORT detected from $cfg"
        fi
        break
    fi
done

# 2. Check package.json scripts for --port flags
if [[ -z "$PORT" ]] && [[ -f "package.json" ]]; then
    SCRIPT_PORT=$(grep -oP '"dev"\s*:\s*"[^"]*--port\s+\K\d+' package.json || true)
    if [[ -n "$SCRIPT_PORT" ]]; then
        PORT="$SCRIPT_PORT"
        echo "Port $PORT detected from package.json dev script"
    fi
fi

# 3. Check next.config.js/ts for custom port (rare)
if [[ -z "$PORT" ]]; then
    for cfg in next.config.js next.config.ts next.config.mjs; do
        if [[ -f "$cfg" ]]; then
            PORT="3000"  # Next.js default
            echo "Next.js detected, using default port $PORT"
            break
        fi
    done
fi

# 4. Check nuxt.config.ts
if [[ -z "$PORT" ]] && [[ -f "nuxt.config.ts" ]]; then
    NUXT_PORT=$(grep -oP 'port\s*:\s*\K\d+' nuxt.config.ts | head -1)
    PORT="${NUXT_PORT:-3000}"
    echo "Nuxt detected, using port $PORT"
fi

# 5. Fall back to framework defaults
if [[ -z "$PORT" ]]; then
    if [[ -f "vite.config.ts" ]] || [[ -f "vite.config.js" ]] || [[ -f "vite.config.mts" ]]; then
        PORT="5173"
    elif [[ -f "svelte.config.js" ]]; then
        PORT="5173"
    else
        PORT="3000"
    fi
    echo "Using default port $PORT"
fi

echo "Will verify at: http://localhost:$PORT"
```

#### 4.5 Detect Dev Command

```bash
DEV_CMD="dev"  # default
if [[ -f "package.json" ]]; then
    if grep -q '"dev"' package.json; then
        DEV_CMD="dev"
    elif grep -q '"start"' package.json; then
        DE