CI/CD & Advanced Usage

This guide covers integrating peek into CI/CD pipelines, advanced usage patterns, and troubleshooting.

GitHub Actions

Basic Layout Check

name: Layout Checks
on: [push, pull_request]

jobs:
  peek-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install peek
        run: npm install -g peek

      - name: Start dev server
        run: npm run dev &
        env:
          PORT: 3000

      - name: Wait for server
        run: npx wait-on http://localhost:3000

      - name: Run layout checks
        run: peek check http://localhost:3000 --format junit &gt; results.xml

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: peek-results
          path: results.xml

Using `peek dev`

If you prefer peek to manage the dev server:

      - name: Run peek dev
        run: peek dev --routes /,/about,/settings --format junit --fail-on error &gt; results.xml

Multi-Route, Multi-Viewport

      - name: Desktop checks
        run: peek check http://localhost:3000 http://localhost:3000/about -v 1920x1080 --format json &gt; desktop.json

      - name: Mobile checks
        run: peek check http://localhost:3000 http://localhost:3000/about --mobile --format json &gt; mobile.json

Screenshot Comparison

Capture screenshots on every PR for visual review:

      - name: Take screenshots
        run: |
          peek snap http://localhost:3000 -o screenshots/home.png
          peek snap http://localhost:3000/about -o screenshots/about.png
          peek snap http://localhost:3000/settings -o screenshots/settings.png

      - name: Upload screenshots
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: screenshots/

Other CI Systems

GitLab CI

peek-check:
  image: node:20
  script:
    - npm ci
    - npm install -g peek
    - npm run dev &
    - npx wait-on http://localhost:3000
    - peek check http://localhost:3000 --format junit &gt; results.xml
  artifacts:
    reports:
      junit: results.xml

Generic CI

The pattern is always the same:

Install peek globally (npm install -g peek)
Start your dev server (or use peek dev)
Run checks with --format junit for CI integration
Use --fail-on error (default) or --fail-on warning to control exit codes

Advanced Patterns

Authenticated Page Checks

For pages behind login, create a setup script and pass it via --setup:

peek check http://localhost:3000/dashboard --setup ./scripts/login.ts --format json

The setup script runs in a temporary page, establishes session cookies, and subsequent checks in the same command are authenticated.

Multiple Viewport Testing

Test responsive layouts by passing multiple viewports:

# Comma-separated viewports
peek check http://localhost:3000 -v 1920x1080,768x1024,375x667

# Or use --mobile for common mobile viewports
peek check http://localhost:3000 --mobile

Selective Checks

Run only the checks you care about:

# Only overflow and clickability
peek check http://localhost:3000 --only overflow,clickability

# Skip touch targets on desktop-focused pages
peek check http://localhost:3000 --only overflow,clickability,visibility,text-overflow,viewport-meta

Browser Pool Management in CI

In CI environments, the browser pool is generally unnecessary since each job starts fresh. You can explicitly disable it:

peek snap http://localhost:3000 --no-pool

For local development with multiple agents, the pool provides significant speedup. Check its status with:

peek pool status
peek pool kill

Scene Checks for Game Engines

If your game engine (Bevy, Unity) can export a scene manifest JSON, peek can run spatial checks:

# Export manifest from your game
my-game --export-scene &gt; manifest.json

# Run peek scene checks
peek scene manifest.json --format json --fail-on warning

Scene checks verify: entity overlap, out-of-bounds entities, zero-size entities, and off-camera visibility.

Troubleshooting

Chrome Not Found

peek auto-downloads Chromium on first use. If this fails in CI:

# Pre-install Chrome
apt-get update && apt-get install -y google-chrome-stable

# Or use the Puppeteer-bundled Chromium
npx @puppeteer/browsers install chromium@latest --path ~/.cache/peek

Screen Recording Permission (macOS)

Native app capture (--app / --pid) requires screen recording permission. On first use, macOS prompts for permission. Grant it in System Settings > Privacy & Security > Screen Recording, then restart your terminal.

Pool Stale State

If the pool gets into a bad state (e.g., Chrome crashed but pool.json was not cleaned up):

peek pool kill
# or manually
rm -rf ~/.peek/pool.json ~/.peek/pool.lock

Hydration Timing

If checks report false positives on SPA pages (React, Next.js, SvelteKit), the page may not be fully hydrated. Use:

peek check http://localhost:3000 --wait-for-hydration

Or specify the framework explicitly:

peek check http://localhost:3000 --wait-for-hydration --framework nextjs

Temporary File Cleanup

peek stores screenshots in /tmp/peek/ by default. Clean them up periodically:

peek clean

Migration from rlint

peek is a drop-in replacement for rlint with additional capabilities:

rlint	peek
`rlint check <url>`	`peek check <url>`
`rlint check <url> --format json`	`peek check <url> --format json`
`rlint dev`	`peek dev`
`rlint dev --routes /,/about`	`peek dev --routes /,/about`

New in peek:

peek snap – screenshots to file
peek snap --app – native window capture (macOS)
peek snap --checks – screenshot + checks in one pass
peek scene – scene checks for game engines
peek pool – browser pool management
peek clean – temp file cleanup
--setup – auth script support on both snap and check