Cypress E2E testing friction points

[jstirnaman]

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 <file> 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 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/<spec>/ 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/<current-spec-name>/ 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/<test>.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: Alpha Scope - Jan 23rd! #1 (reuse Hugo server) + Alpha - Flux #2 (test name filter) — saves ~80% of iteration time
2. Medium: V2 layout #3 (clean screenshots), Collapsable left nav #4 (HTML dumps), Add rel=canonical to old versions #6 (quiet mode) — QoL improvements
3. Low: Add Google Analytics #5 (auto-detect mapping), Various style updates #7 (fast-render), Add favicon #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