Imported from ilangurudev/personal-portfolio (tests/AGENTS.md). Install upstream with npx skills add ilangurudev/personal-portfolio --skill tests. Copyright stays with the author.

Development & Testing

1. Determining Environment

First determine if the env var PUBLIC_ENV is "DEV". If it is, then you are in a local environment. Else you are probably in a remote (sandboxed) environment.

Local Env Instructions

In a local environment, environment is mostly setup for you. You can check if a dev server is already running. If not, you can start by npm run dev # Start dev server (http://localhost:4321)

Remove Env

If you're running tests in a remote or sandboxed environment (e.g., Claude Code web, Codespaces, containers) where PUBLIC_ENV is not DEV, setup environment with SKIP_CHROMIUM_INSTALL=1 bash tests/setup-remote-e2e.sh.

see SETUP-REMOTE.md for detailed troubleshooting instructions including:

• Installing dependencies
• Installing Playwright/Chromium
• Starting the dev server
• Troubleshooting common issues
  • If Chromium downloads are blocked, set SKIP_CHROMIUM_INSTALL=1 and point PLAYWRIGHT_BROWSERS_PATH (or ${HOME}/.cache/ms-playwright) to a preinstalled browser.

2. Testing

E2E Tests (Playwright):

npm test                  # Run ALL specs in parallel (new runner)
npm run test:serial       # Run ALL specs sequentially (previous flow)
npm run test:navigation   # Dual-space navigation
npm run test:responsive   # Responsive layouts
npm run test:visual       # Visual aesthetics
npm run test:filters      # Simple filter toggle (All/Street/Landscape)
npm run test:tag-and-or   # Tag filtering with AND/OR modes
npm run test:tag-story    # Newest-first editorial layout on photography tag pages
npm run test:lightbox     # Lightbox open/close/navigation
npm run test:story        # Story drawer functionality
npm run test:story-anchors # Featured anchor spacing, image sources, refresh rhythm, lightbox order
npm run test:nav-links    # Tag/album links in lightbox
npm run test:scroll       # Infinite scroll / lazy loading
npm run test:advanced-filters # 8-dimensional filter panel
npm run test:slideshow    # Slideshow mode
npm run test:albums       # Album pages functionality
npm run test:sorting      # Photo sorting
npm run test:css-leaks    # CSS rendering leak detection
npm run test:viewfinder   # Viewfinder overlay CSS functionality
npm run test:photo-hover  # Shared color-preserving frame across homepage, album, tag, and Archive photographs
npm run test:photo-editorial # Curated photography IA and editorial acceptance contract
npm run test:photo-scroll-story # Homepage motion hierarchy, reduced motion, and natural scrolling
npm run test:photo-motion # Shared motion profiles across stories, indexes, Archive, and search
npm run test:about-anchor # About hash remains stable while homepage photographs lazy-load

Parallel runner options:

• E2E_CONCURRENCY: Specs to run at once (defaults to CPU count; capped by spec count).
• E2E_LOG_THROUGH=true: Stream each spec's output live with [spec] prefixes.
• HEADLESS=true: Run browsers headless (recommended in remote/CI).
• Failures are summarized at the end with captured output for failing specs only.

Headless vs headed:

• Browsers run headless by default (we set HEADLESS=true unless overridden).
• To watch interactions locally, set HEADLESS=false for a single run.

Test Files:

Note: Tests are run via Playwright. Ensure the dev server is running (npm run dev) before running tests. The Playwright runner now watches for any ✗ output or console.error in specs and exits non-zero so failures are visible.

tests/unit/vegas-capture-dates.test.ts verifies all 169 Las Vegas timestamps retain the recorded timezone and that the Hoover Dam/casino sequence survives the camera filename counter rollover, including the editorial layout pass.

3. Build Gotchas

1. Image Path: filename in photo frontmatter is relative to public/photos/
2. EXIF: Frontmatter is source of truth (no runtime extraction)
3. Tags: Case-sensitive, keep consistent (recommend lowercase)
4. Content Collections Warning: src/content/loaders/ triggers auto-collection warning (safe to ignore)
5. First Build: May be slow due to Sharp image processing; subsequent builds use cache