Cypress E2E testing friction points

Nobody has claimed this yet.

## Summary

Cypress E2E testing has significant friction points that slow down development iteration. The top two issues (Hugo startup and test filtering) account for ~80% of wasted time during test-driven template development.

## Impact

- Single-test iteration: **>2 minutes** (75s Hugo boot + 60-90s test)
- With reusable Hugo server: **~15 seconds** (just test execution)
- Cannot target individual `it()` blocks without risky `.only()` edits

## Friction Points (Ranked by Time Cost)

### 1. Cypress always boots its own Hugo (~75s startup per run) 🔴

**Problem**: Can't reuse a running dev server. Even when only changing a template, iteration = 75s Hugo + 60-90s test = >2m.

**Solution**: Add `--use-existing-server` flag pointing at `localhost:1313` to cut iteration to ~15s.

**Worktree consideration**: Hugo would need to auto-select a port and we'd need to pass it to Cypress.

---

### 2. Can't target a single `it()` block 🔴

**Problem**: `run-e2e-specs.js` only accepts `--spec ` and `--no-mapping`. To iterate on one failing test, must either:
- Edit spec with `.only()` (risky to forget and commit)
- Wait through all 25 tests in the file

**Solution**: Add `--grep "test name pattern"` passthrough to Cypress's `--env grep=` functionality using the [@cypress/grep](https://github.com/cypress-io/cypress-grep) plugin.

**Current limitation**: Confirmed in `cypress/support/run-e2e-specs.js:46` - `parseArgs` only handles `--spec` and `--no-mapping`.

---

### 3. Old failure screenshots aren't cleaned between runs 🟡

**Problem**: `cypress/screenshots//` accumulates. After multiple runs, 20+ `(failed) (2).png` files from previous sessions clutter the directory. Must use `ls -lt` to find today's screenshots.

**Solution**: Runner should `rm -rf cypress/screenshots//` on start.

---

### 4. No HTML dump on failure — only PNG 🟡

**Problem**: Screenshots are hard to parse for "which selector is missing." Debugging requires eyeballing images instead of searching DOM.

**Solution**: Write `document.documentElement.outerHTML` to `cypress/failures/.html` in `afterEach` when test fails. Would enable `grep` instead of visual inspection.

---

### 5. "No file paths provided" when spec is spec-only 🟡

**Problem**: The runner's content-mapping mode is a footgun for tests like `api-reference.cy.js` that don't track individual content files and use raw `cy.visit()`.

**Solution**: Auto-detect: if every test does a raw `cy.visit()`, skip mapping mode automatically.

---

### 6. Verbose output forces `| tail -40` every time 🟡

**Problem**: 90% of needed info is "which tests failed and their assertion errors." ASCII tables, spec runner chrome, and video encoding lines bury the signal.

**Solution**: Add `--quiet` mode that suppresses verbose formatting and only shows failures and errors.

---

### 7. Hugo fast-render disabled for Cypress 🟠

**Problem**: `--disableFastRender` used as workaround for 0.157.0 panic. Every page request re-renders fully = several seconds per page × many `cy.visit()` calls.

**Solution**: Check if upstream bug is fixed or isolate the bad template to re-enable fast render.

**Context**: See Hugo usage in Cypress config/setup files.

---

### 8. `/tmp/hugo_server.log` errors not surfaced 🟠

**Problem**: Failed Cypress run points to this log, but must manually read it separately.

**Solution**: Runner could `grep` the log for `ERROR`/`WARN` on test failure and include it in output automatically.

---

## Recommended Priority

1. **High**: #1 (reuse Hugo server) + #2 (test name filter) — saves ~80% of iteration time
2. **Medium**: #3 (clean screenshots), #4 (HTML dumps), #6 (quiet mode) — QoL improvements
3. **Low**: #5 (auto-detect mapping), #7 (fast-render), #8 (surface logs) — nice-to-haves

## Files to Modify

- `cypress/support/run-e2e-specs.js` — test runner and CLI args
- `cypress.config.js` — Hugo server configuration
- `cypress/support/e2e.js` — failure handlers and cleanup

Start with cypress/support/run-e2e-specs.js, cypress.config.js, and cypress/support/e2e.js, then trace how the runner starts Hugo, parses arguments, handles failures, and maps content. Narrow the work to the ranked priorities before changing anything; done should mean the selected improvements are implemented and the stated Cypress iteration and failure-reporting friction is reduced.

Written by the indexing model from the issue text.