Testing Frontend

Testing Frontend — Verification & Quality Assurance

Ensure the storybook experience works flawlessly across devices, browsers, and interaction modes before every deploy.

Overview

A full-screen, animation-heavy landing page has unique testing challenges that standard unit tests don't cover:

This guide covers the four testing layers needed:

Layer 4:  Performance & Lighthouse CI        (automated budget)
Layer 3:  Visual Regression Testing          (screenshot diffs)
Layer 2:  Integration / E2E Testing          (real browser interactions)
Layer 1:  Unit & Component Tests             (logic + render checks)

1 — Unit & Component Tests

Setup

npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom

// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import path from "path";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: ["./tests/setup.ts"],
  },
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "."),
    },
  },
});

// tests/setup.ts
import "@testing-library/jest-dom/vitest";

// Mock framer-motion to avoid animation timing issues
vi.mock("framer-motion", async () => {
  const actual = await vi.importActual("framer-motion");
  return {
    ...actual,
    AnimatePresence: ({ children }: any) => children,
    motion: new Proxy(
      {},
      {
        get: (_target, prop) => {
          // Return a simple component that passes through props
          return ({ children, ...props }: any) => {
            const Component = prop as string;
            return <Component {...props}>{children}</Component>;
          };
        },
      }
    ),
  };
});

What to Unit Test

Example: Scene Config Validation

// tests/scene-config.test.ts
import { PAGES } from "@/components/seer/config";

describe("Scene Configuration", () => {
  it("every scene has a unique id", () => {
    const ids = PAGES.map((p) => p.id);
    expect(new Set(ids).size).toBe(ids.length);
  });

  it("every scene has a title and subtitle", () => {
    PAGES.forEach((page, i) => {
      expect(page.title, `Scene ${i} missing title`).toBeTruthy();
      expect(page.subtitle, `Scene ${i} missing subtitle`).toBeTruthy();
    });
  });

  it("mascot has a position for every scene", () => {
    PAGES.forEach((page, i) => {
      expect(page.mascotPosition, `Scene ${i} missing mascotPosition`).toBeDefined();
    });
  });

  it("all gradient values are valid CSS", () => {
    PAGES.forEach((page) => {
      if (page.gradient) {
        expect(page.gradient).toMatch(/^(linear|radial|conic)-gradient/);
      }
    });
  });
});

Example: Hash Navigation Mapping

// tests/hash-navigation.test.ts
const HASH_MAP: Record<string, number> = {
  "#signup": 9,
  "#demo": 8,
  "#faq": 10,
};

describe("Hash Navigation", () => {
  Object.entries(HASH_MAP).forEach(([hash, expected]) => {
    it(`${hash} → scene ${expected}`, () => {
      expect(HASH_MAP[hash]).toBe(expected);
    });
  });

  it("unknown hash returns undefined (falls back to 0)", () => {
    expect(HASH_MAP["#nonexistent"]).toBeUndefined();
  });
});

Example: Intro Skip Logic

// tests/intro-skip.test.ts
describe("Intro Sequence Skip", () => {
  beforeEach(() => {
    sessionStorage.clear();
  });

  it("first visit does not skip intro", () => {
    const seen = sessionStorage.getItem("introSeen");
    expect(seen).toBeNull();
  });

  it("sets flag after intro completes", () => {
    sessionStorage.setItem("introSeen", "true");
    expect(sessionStorage.getItem("introSeen")).toBe("true");
  });

  it("subsequent visits skip intro", () => {
    sessionStorage.setItem("introSeen", "true");
    const shouldSkip = sessionStorage.getItem("introSeen") === "true";
    expect(shouldSkip).toBe(true);
  });
});

2 — Integration / E2E Tests (Playwright)

Setup

npm install -D @playwright/test
npx playwright install

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests/e2e",
  timeout: 30_000,
  retries: 1,
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    video: "on-first-retry",
  },
  projects: [
    { name: "Desktop Chrome", use: { ...devices["Desktop Chrome"] } },
    { name: "Desktop Firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "Mobile Safari", use: { ...devices["iPhone 14"] } },
    { name: "Mobile Chrome", use: { ...devices["Pixel 7"] } },
  ],
  webServer: {
    command: "npm run dev",
    port: 3000,
    reuseExistingServer: true,
  },
});

Test: Scene Navigation via Scroll

// tests/e2e/navigation.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Scene Navigation", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto("/");
    // Wait for intro to complete or skip it
    await page.waitForTimeout(4000); // Intro duration
  });

  test("wheel down advances to next scene", async ({ page }) => {
    // Start at scene 0 (Hero)
    const hero = page.locator("[data-scene='hero']");
    await expect(hero).toBeVisible();

    // Scroll down
    await page.mouse.wheel(0, 200);
    await page.waitForTimeout(1500); // Transition duration

    // Should now be on scene 1
    const scene1 = page.locator("[data-scene='threat']");
    await expect(scene1).toBeVisible();
  });

  test("keyboard ArrowDown advances scene", async ({ page }) => {
    await page.keyboard.press("ArrowDown");
    await page.waitForTimeout(1500);

    const scene1 = page.locator("[data-scene='threat']");
    await expect(scene1).toBeVisible();
  });

  test("page indicator dots are clickable", async ({ page }) => {
    // Click the 3rd dot
    const dot = page.locator("[data-page-dot='2']");
    await dot.click();
    await page.waitForTimeout(1500);

    // Scene 2 should be visible
    const scene2 = page.locator("[data-scene='solution']");
    await expect(scene2).toBeVisible();
  });
});

Test: Touch Swipe (Mobile)

// tests/e2e/touch-navigation.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Touch Navigation", () => {
  test.use({ ...devices["iPhone 14"] });

  test("swipe up advances to next scene", async ({ page }) => {
    await page.goto("/");
    await page.waitForTimeout(4000);

    // Simulate swipe up
    await page.touchscreen.tap(200, 600);
    await page.mouse.move(200, 600);
    await page.mouse.down();
    await page.mouse.move(200, 200, { steps: 10 }); // Swipe up
    await page.mouse.up();

    await page.waitForTimeout(1500);

    const scene1 = page.locator("[data-scene='threat']");
    await expect(scene1).toBeVisible();
  });
});

Test: Intro Sequence

// tests/e2e/intro.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Intro Sequence", () => {
  test("plays full intro on first visit", async ({ page, context }) => {
    // Clear session storage
    await context.clearCookies();

    await page.goto("/");

    // Intro overlay should be visible
    const intro = page.locator("[data-testid='intro-sequence']");
    await expect(intro).toBeVisible();

    // Wait for intro to complete
    await page.waitForTimeout(4500);

    // Hero scene should now be visible
    const hero = page.locator("[data-scene='hero']");
    await expect(hero).toBeVisible();
  });

  test("skips intro on subsequent visits", async ({ page }) => {
    // First visit
    await page.goto("/");
    await page.waitForTimeout(5000);

    // sessionStorage should now have the flag
    const flag = await page.evaluate(() =>
      sessionStorage.getItem("introSeen")
    );
    expect(flag).toBe("true");

    // Reload — intro should be skipped
    await page.reload();
    await page.waitForTimeout(500);

    const hero = page.locator("[data-scene='hero']");
    await expect(hero).toBeVisible();
  });
});

Test: Form Submission

// tests/e2e/signup-form.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Sign-Up Form", () => {
  test("submits valid form and shows success", async ({ page }) => {
    await page.goto("/#signup");
    await page.waitForTimeout(2000);

    await page.fill("[name='email']", "test@example.com");
    await page.fill("[name='name']", "Test User");
    await page.click("[type='submit']");

    // Should show success state
    const success = page.locator("[data-testid='signup-success']");
    await expect(success).toBeVisible({ timeout: 5000 });
  });

  test("shows validation error for invalid email", async ({ page }) => {
    await page.goto("/#signup");
    await page.waitForTimeout(2000);

    await page.fill("[name='email']", "not-an-email");
    await page.click("[type='submit']");

    const error = page.locator("[data-testid='email-error']");
    await expect(error).toBeVisible();
  });
});

3 — Visual Regression Testing

Why Screenshots Matter

CSS-only animations, glassmorphism effects, and gradient overlays can break silently — no test runner catches a misaligned gradient.

Playwright Visual Comparisons

// tests/e2e/visual.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Visual Regression", () => {
  const scenes = ["hero", "threat", "solution", "product", "process", "stats"];

  for (const scene of scenes) {
    test(`scene "${scene}" matches snapshot`, async ({ page }) => {
      await page.goto("/");
      await page.waitForTimeout(4500); // Wait for intro

      // Navigate to the target scene
      await page.evaluate((s) => {
        // Use the exposed goToPage function
        (window as any).__goToPage?.(s);
      }, scene);

      await page.waitForTimeout(2000); // Wait for transition

      // Take screenshot and compare
      await expect(page).toHaveScreenshot(`${scene}-desktop.png`, {
        maxDiffPixelRatio: 0.02, // Allow 2% pixel difference
        animations: "disabled",   // Freeze CSS animations
      });
    });
  }
});

Mobile Visual Regression

test.describe("Mobile Visual Regression", () => {
  test.use({ ...devices["iPhone 14"] });

  test("hero scene mobile layout", async ({ page }) => {
    await page.goto("/");
    await page.waitForTimeout(4500);

    await expect(page).toHaveScreenshot("hero-mobile.png", {
      maxDiffPixelRatio: 0.02,
      animations: "disabled",
    });
  });

  test("mascot is hidden on mobile", async ({ page }) => {
    await page.goto("/");
    await page.waitForTimeout(4500);

    const mascot = page.locator("[data-testid='mascot']");
    await expect(mascot).not.toBeVisible();
  });
});

Updating Snapshots

# Update all snapshots after intentional visual changes
npx playwright test --update-snapshots

# Update specific test snapshots
npx playwright test visual.spec.ts --update-snapshots

4 — Performance Testing

Lighthouse CI

npm install -D @lhci/cli

// lighthouserc.json
{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000"],
      "startServerCommand": "npm run start",
      "numberOfRuns": 3,
      "settings": {
        "preset": "desktop"
      }
    },
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 0.9 }],
        "categories:best-practices": ["warn", { "minScore": 0.85 }],
        "first-contentful-paint": ["error", { "maxNumericValue": 1500 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "total-blocking-time": ["error", { "maxNumericValue": 200 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
      }
    }
  }
}

# Run Lighthouse CI
npx lhci autorun

Manual Performance Profiling

For animation-specific performance that automated tools miss:

1. Open Chrome DevTools → Performance tab
2. Enable "CPU 4x slowdown" (simulates low-end device)
3. Start recording
4. Navigate through all scenes (wheel / click dots)
5. Stop recording
6. Check for:
   - Frame drops below 60 fps during transitions
   - Long tasks (> 50ms) blocking the main thread
   - Excessive layout recalculations (reflows)
   - Memory leaks (heap growing without release)

Runtime Animation Frame Budget

// Debug-only: monitor frame rate during development
if (process.env.NODE_ENV === "development") {
  let lastTime = performance.now();
  let frames = 0;

  const measureFPS = () => {
    frames++;
    const now = performance.now();
    if (now - lastTime >= 1000) {
      console.log(`FPS: ${frames}`);
      frames = 0;
      lastTime = now;
    }
    requestAnimationFrame(measureFPS);
  };

  requestAnimationFrame(measureFPS);
}

5 — Accessibility Testing

Automated A11y Checks

npm install -D @axe-core/playwright

// tests/e2e/accessibility.spec.ts
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test.describe("Accessibility", () => {
  test("hero scene has no critical a11y violations", async ({ page }) => {
    await page.goto("/");
    await page.waitForTimeout(4500);

    const results = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa"])
      .analyze();

    expect(results.violations.filter((v) => v.impact === "critical")).toEqual([]);
  });

  test("keyboard navigation works through all scenes", async ({ page }) => {
    await page.goto("/");
    await page.waitForTimeout(4500);

    // Tab should reach interactive elements
    await page.keyboard.press("Tab");
    const focused = await page.evaluate(() =>
      document.activeElement?.tagName
    );
    expect(focused).toBeTruthy();
  });

  test("all images have alt text", async ({ page }) => {
    await page.goto("/");
    await page.waitForTimeout(4500);

    const imagesWithoutAlt = await page.$$eval(
      "img:not([alt])",
      (imgs) => imgs.length
    );
    expect(imagesWithoutAlt).toBe(0);
  });
});

Manual A11y Checklist

• All interactive elements reachable via keyboard (Tab/Shift+Tab)
• ArrowUp/ArrowDown navigate scenes (plus Escape for special actions)
• Focus indicators visible on all interactive elements
• Color contrast ratio ≥ 4.5:1 for body text, ≥ 3:1 for large text
• prefers-reduced-motion disables non-essential animations
• Screen reader announces scene changes (aria-live region)
• Form fields have associated labels

Reduced Motion Support

// Detect and respect user preference
const prefersReducedMotion =
  typeof window !== "undefined" &&
  window.matchMedia("(prefers-reduced-motion: reduce)").matches;

// Use for framer-motion variants
const transition = prefersReducedMotion
  ? { duration: 0 }
  : { type: "spring", stiffness: 120, damping: 20 };

// CSS fallback
// @media (prefers-reduced-motion: reduce) {
//   *, *::before, *::after {
//     animation-duration: 0.01ms !important;
//     transition-duration: 0.01ms !important;
//   }
// }

6 — Cross-Browser Test Matrix

Known Cross-Browser Issues

7 — CI Pipeline Integration

GitHub Actions Example

# .github/workflows/test.yml
name: Test & Quality

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx vitest run

  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npx lhci autorun

Test Commands Quick Reference

# Unit tests
npx vitest              # Watch mode
npx vitest run          # Single run
npx vitest run --coverage  # With coverage

# E2E tests
npx playwright test                    # All browsers
npx playwright test --project="Desktop Chrome"  # One browser
npx playwright test --ui               # Interactive UI mode
npx playwright test --debug            # Step-through debugger

# Visual regression
npx playwright test visual.spec.ts
npx playwright test --update-snapshots # After intentional changes

# Lighthouse
npx lhci autorun

# Type checking
npx tsc --noEmit

# Lint
npm run lint

Testing Checklist

• Scene config validation (unit test)
• Hash navigation mapping (unit test)
• Intro skip logic (unit test)
• Wheel navigation advances scenes (E2E)
• Keyboard navigation works (E2E)
• Touch swipe navigation works (E2E, mobile project)
• Form submit + validation (E2E)
• Visual snapshots for each scene (visual regression)
• Mobile layout snapshots (visual regression)
• Mascot hidden on mobile (E2E assertion)
• Lighthouse scores within budget (performance)
• No critical a11y violations (accessibility)
• Works in Chrome, Safari, Firefox (cross-browser)
• No console errors during full navigation (E2E)
• CI pipeline runs all test layers on PR

← Back to: Master SKILL.md