serve-and-test

---
name: serve-and-test
description: "Start a clean local HTTP server for static files, open in Playwright with cache-busting, and provide teardown. Use when the user says 'serve this', 'open in browser', 'test locally', 'start a server', or when working with static HTML/CSS/JS files that need browser testing. Handles port conflicts, stale process cleanup, and cache-busting navigation."
---

# Serve and Test — Local HTTP Server with Browser Automation

Serve static files over HTTP, open in Playwright, and handle the full lifecycle cleanly.

## When to Use

- Testing static HTML/CSS/JS files that need a browser
- Another skill needs browser automation on local files (Playwright blocks `file://`)
- User wants to preview or test a local web page

## Step 1: Kill Any Existing Server on the Port

Always clean up first. Stale servers from previous runs are the #1 cause of serving outdated files.

```bash
PORT=8765
lsof -ti:$PORT | xargs kill -9 2>/dev/null
sleep 1
```

## Step 2: Start the Server

```bash
cd "/path/to/project" && python3 -m http.server $PORT &
SERVER_PID=$!
echo "Server PID: $SERVER_PID"
sleep 1
# Verify it's serving the correct content:
curl -s http://localhost:$PORT/index.html | head -5
```

Use port 8765 by default (avoids conflicts with common dev servers on 3000/5173/8080).

## Step 3: Navigate with Cache-Busting

When opening in Playwright, always append a cache-busting query parameter:

```
http://localhost:8765/index.html?v=TIMESTAMP
```

This forces the browser to fetch fresh content even if it has a cached version. This is critical after file edits — without cache-busting, the browser may serve stale content and your tests will pass/fail incorrectly.

**After editing files and re-testing**: increment the query parameter or use a new timestamp:
```
http://localhost:8765/index.html?v=2
http://localhost:8765/index.html?v=3
```

## Step 4: Run Tests

Use Playwright MCP tools to:
1. Take screenshots (`browser_take_screenshot`)
2. Click elements (`browser_click`)
3. Evaluate JS assertions (`browser_evaluate`)
4. Take more screenshots after interactions

## Step 5: Teardown

When done testing:

```bash
lsof -ti:$PORT | xargs kill -9 2>/dev/null
echo "Server stopped"
```

Always clean up — orphaned `python3 -m http.server` processes accumulate across sessions.

## Troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| "Address already in use" | Stale server on same port | `lsof -ti:PORT \| xargs kill -9` |
| Old content served after edit | Browser cache or wrong server | Cache-bust with `?v=N` and verify with `curl` |
| `file://` blocked in Playwright | Playwright security policy | Must use HTTP server — that's what this skill is for |
| Server exits immediately | Port conflict or path error | Check `lsof -ti:PORT` and verify the directory exists |