Update testing instructions

Author: st0012

.claude/skills/test-server/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: test-server
+description: E2E testing workflow for the RDoc live-reload server (rdoc --server)
+---
+
+# Test Server
+
+End-to-end testing workflow for the RDoc live-reload server. Use after modifying server code, templates, generators, or routing.
+
+## Steps
+
+### 1. Start the server
+
+```bash
+bundle exec rdoc --server &
+SERVER_PID=$!
+sleep 2  # wait for TCP server to bind
+```
+
+Or on a custom port:
+
+```bash
+bundle exec rdoc --server=8080 &
+```
+
+Default port is 4000.
+
+### 2. Verify core endpoints
+
+Run these curl checks against the running server:
+
+```bash
+# Root → 200, HTML index page
+curl -s -o /dev/null -w '%{http_code}' http://localhost:4000/
+# Expected: 200
+
+# Status endpoint → 200, JSON with last_change float
+curl -s http://localhost:4000/__status
+# Expected: {"last_change":1234567890.123}
+
+# Class page → 200, HTML with live-reload script
+curl -s http://localhost:4000/RDoc.html | head -5
+# Expected: HTML containing class documentation
+
+# CSS asset → 200, stylesheet
+curl -s -o /dev/null -w '%{http_code}' http://localhost:4000/css/rdoc.css
+# Expected: 200
+
+# JS search index → 200, search data
+curl -s -o /dev/null -w '%{http_code}' http://localhost:4000/js/search_data.js
+# Expected: 200
+
+# Missing page → 404, still has live-reload script
+curl -s -w '\n%{http_code}' http://localhost:4000/Missing.html | tail -1
+# Expected: 404
+
+# Path traversal via asset route → 404 (blocked by expand_path check)
+curl -s -o /dev/null -w '%{http_code}' 'http://localhost:4000/css/../../etc/passwd'
+# Expected: 404
+```
+
+### 3. Verify live-reload
+
+HTML pages should contain the live-reload polling script:
+
+```bash
+# Check for live-reload script in a class page
+curl -s http://localhost:4000/RDoc.html | grep 'var lastChange'
+# Expected: var lastChange = <float>;
+
+# Check that 404 pages also get live-reload
+curl -s http://localhost:4000/Missing.html | grep 'var lastChange'
+# Expected: var lastChange = <float>;
+```
+
+The script polls `/__status` and reloads when `data.last_change > lastChange`.
+
+### 4. Verify file change detection
+
+Confirm the server detects source file changes and invalidates its cache:
+
+```bash
+# Record the current last_change timestamp
+BEFORE=$(curl -s http://localhost:4000/__status | grep -o '"last_change":[0-9.]*' | cut -d: -f2)
+
+# Touch a source file to trigger the file watcher
+touch lib/rdoc.rb
+sleep 2  # watcher polls every 1 second
+
+# Check that last_change has advanced
+AFTER=$(curl -s http://localhost:4000/__status | grep -o '"last_change":[0-9.]*' | cut -d: -f2)
+echo "before=$BEFORE after=$AFTER"
+# Expected: AFTER > BEFORE
+```
+
+### 5. (Optional) Visual testing with Playwright CLI
+
+For visual inspection of rendered pages, use Playwright CLI commands directly:
+
+```bash
+# Install browsers (one-time)
+npx playwright install chromium
+
+# Take a screenshot of the index page
+npx playwright screenshot http://localhost:4000/ /tmp/rdoc-index.png
+
+# Take a screenshot of a specific class page
+npx playwright screenshot http://localhost:4000/RDoc.html /tmp/rdoc-class.png
+
+# Full-page screenshot
+npx playwright screenshot --full-page http://localhost:4000/RDoc.html /tmp/rdoc-full.png
+```
+
+Review the screenshots to verify layout, styling, and content rendering.
+
+### 6. Stop the server
+
+```bash
+kill $SERVER_PID 2>/dev/null
+```

AGENTS.md

@@ -353,15 +353,34 @@ When making changes to theme CSS or templates (e.g., Darkfish or Aliki themes):
 1. **Start the live-reloading server**: Run `bundle exec rdoc --server` (or `bundle exec rake rdoc:server`)
 2. **Make changes**: Edit files in `lib/rdoc/generator/template/<theme>/` or source code
 3. **Browser auto-refreshes**: The server detects file changes and refreshes the browser automatically
-4. **Investigate with Playwright**: Ask the AI assistant to take screenshots and inspect the documentation visually
-   - Example: "Navigate to the docs at localhost:4000 and screenshot the RDoc module page"
-   - See "Playwright MCP for Testing Generated Documentation" section below for details
+4. **Verify with `/test-server`**: Use the test-server skill for endpoint checks, live-reload verification, and optional Playwright screenshots
 5. **Lint changes** (if modified):
    - ERB templates: `npx @herb-tools/linter "lib/rdoc/generator/template/**/*.rhtml"`
    - CSS files: `npm run lint:css -- --fix`
 
 **Note:** The server watches source files, not template files. If you modify `.rhtml` templates or CSS in the template directory, restart the server to pick up those changes.
 
+## Visual Testing with Playwright CLI
+
+Use `npx playwright` to take screenshots of generated documentation — works with both the live-reload server and static `_site/` output.
+
+```bash
+# Install browsers (one-time)
+npx playwright install chromium
+
+# Screenshot a live server page
+npx playwright screenshot http://localhost:4000/RDoc.html /tmp/rdoc-class.png
+
+# Screenshot static output (start a file server first)
+cd _site && python3 -m http.server 8000 &
+npx playwright screenshot http://localhost:8000/index.html /tmp/rdoc-index.png
+
+# Full-page screenshot
+npx playwright screenshot --full-page http://localhost:4000/RDoc.html /tmp/rdoc-full.png
+```
+
+For server-specific E2E testing (endpoint checks, live-reload verification, file change detection), use the `/test-server` skill.
+
 ## Notes for AI Agents
 
 1. **Always run tests** after making changes: `bundle exec rake`
@@ -373,68 +392,3 @@ When making changes to theme CSS or templates (e.g., Darkfish or Aliki themes):
 4. **Use `rake rerdoc`** to regenerate documentation (not just `rdoc`)
 5. **Verify generated files** with `rake verify_generated`
 6. **Don't edit generated files** directly (in `lib/rdoc/markdown/` and `lib/rdoc/rd/`)
-
-## Playwright MCP for Testing Generated Documentation
-
-The Playwright MCP server enables visual inspection and interaction with generated HTML documentation. This is useful for verifying CSS styling, layout issues, and overall appearance.
-
-**MCP Server:** `@playwright/mcp` (Microsoft's official browser automation server)
-
-### Setup
-
-The Playwright MCP server can be used with any MCP-compatible AI tool (Claude Code, Cursor, GitHub Copilot, OpenAI Agents, etc.).
-
-**Claude Code:**
-
-```bash
-/plugin playwright
-```
-
-**Other MCP-compatible tools:**
-
-```bash
-npx @playwright/mcp@latest
-```
-
-Configure your tool to connect to this MCP server. Playwright launches its own browser instance automatically - no manual browser setup or extensions required.
-
-### Troubleshooting: Chrome Remote Debugging Blocked
-
-If you encounter `DevTools remote debugging is disallowed by the system admin`, Chrome's debugging is blocked by the machine's policy. Use Firefox instead:
-
-```bash
-# Install Firefox for Playwright
-npx playwright install firefox
-
-# Add Playwright MCP with Firefox to your project (creates/updates .mcp.json)
-claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest --browser firefox
-```
-
-Restart Claude Code after running these commands.
-
-### Testing Generated Documentation
-
-The easiest way to test documentation is with the live-reloading server:
-
-```bash
-bundle exec rdoc --server
-# Or: bundle exec rake rdoc:server
-```
-
-This starts a server at `http://localhost:4000` that auto-refreshes on file changes.
-
-Alternatively, for testing static output:
-
-```bash
-bundle exec rake rerdoc
-cd _site && python3 -m http.server 8000
-```
-
-Then ask the AI assistant to inspect the documentation. It will use the appropriate Playwright tools (`browser_navigate`, `browser_snapshot`, `browser_take_screenshot`, etc.) based on your request.
-
-**Example requests:**
-
-- "Navigate to `http://localhost:4000` and take a screenshot"
-- "Take a screenshot of the RDoc module page"
-- "Check if code blocks are rendering properly on the Markup page"
-- "Compare the index page before and after my CSS changes"