testing-pd-hunter-frontend

name	testing-pd-hunter-frontend
description	Test the PD-Hunter Next.js frontend end-to-end. Use when verifying UI changes, routing, or data display.

Testing PD-Hunter Frontend

Prerequisites

• Node.js 18+ installed
• enriched_bounties.json present at repo root (used by api-server.ts as fallback)

Setup

cd frontend
npm install
npm run build   # generates static export in out/

Serving for Testing

Use static build, NOT dev server for testing routes with output: "export". The dev server has strict generateStaticParams enforcement that may differ from production behavior.

npm install -g serve
serve frontend/out -l 3002 --no-clipboard
# WITHOUT -s flag (SPA mode breaks static routing)

Clean URLs work automatically with serve (e.g., /bounty/commaai-flash--42 maps to commaai-flash--42.html).

Do NOT use serve -s — it enables SPA fallback that serves index.html for all routes, breaking static page routing.

Do NOT use Python http.server — it doesn't handle clean URLs (requires .html extension).

Key Test Scenarios

Bounty Detail Routes

• Bounty detail pages use composite slug format: /bounty/{owner}-{repo}--{number}
• The bountySlug() function in frontend/src/lib/utils.ts generates slugs
• Collision data (as of May 2026): #42 (flash/website), #30 (agnos-builder/website)

Backward Compatibility

• Unique bare numbers (e.g., /bounty/2281) resolve directly to the bounty
• Colliding bare numbers (e.g., /bounty/42) show a disambiguation page (BountyDisambiguation.tsx)
• Non-existent numbers return 404

Data Loading

• Homepage loads data client-side from ./data/enriched_bounties.json
• Bounty detail pages are statically generated (SSG) — data is baked into HTML at build time
• Data endpoint: /data/enriched_bounties.json

Verification Commands

# Lint and typecheck
cd frontend && npm run lint && npx tsc --noEmit

# Check build generates expected page count
npm run build 2>&1 | grep "Generating static pages"

# Verify no duplicate static paths
ls frontend/out/bounty/ | sort | uniq -d  # should be empty

# Verify collision files exist separately
ls frontend/out/bounty/ | grep -E '(flash--42|website--42)'

Common Issues

• Dev server (npm run dev) might fail with "missing param in generateStaticParams" for dynamically added routes — use static build instead
• Homepage may show "Loading bounties" indefinitely in dev mode if the data file path doesn't resolve — this is a dev-mode issue, not a production bug
• The serve package requires explicit --no-clipboard on headless environments

Devin Secrets Needed

None — no authentication required for local testing.