Visual Testing Guide

Documentation for reproducing screenshots and visual verification tests. Essential for regression testing after CSS changes or UI updates.

---

Prerequisites

• Playwright MCP server configured
• Site running at https://help.l.homestar.ink
• Browser with dark mode toggle support

---

Screenshot Workflow

Dark Mode Code Block Verification

Purpose: Verify code blocks have proper contrast in dark mode

Page: Properties API Reference

1. Navigate to https://help.l.homestar.ink/reference/properties/
2. Toggle dark mode (theme switcher in header)
3. Scroll to “Example Response” section
4. Take screenshot showing:
   • Sidebar with warm orange theme badges
   • Code blocks with dark backgrounds (#1a1814)
   • Syntax highlighting with high contrast
   • Inline code elements in tables

What to verify:

• ✅ Dark background on code blocks (not light beige)
• ✅ Readable syntax highlighting colors
• ✅ Inline code has dark background
• ✅ Terminal-style curl commands have dark background
• ✅ JSON blocks show colorful but readable tokens

Playwright automation:

await browser_navigate({
  url: "https://help.l.homestar.ink/reference/properties/"
});
// Toggle dark mode first
await browser_take_screenshot({
  filename: "dark-mode-code-blocks.png"
});

---

Light Mode Code Block Verification

Purpose: Verify code blocks have proper contrast in light mode

Same page as dark mode test

1. Navigate to https://help.l.homestar.ink/reference/properties/
2. Toggle light mode (if currently in dark mode)
3. Scroll to code examples
4. Take screenshot showing:
   • Light cream page background
   • Code blocks with light backgrounds (#f5f2ed)
   • Dark text with high contrast

What to verify:

• ✅ Light background on code blocks (not dark)
• ✅ Dark text with high contrast (#1f1d1a)
• ✅ Warm cream page background maintained (#faf8f4)
• ✅ Orange accent colors preserved

---

Screenshot Storage

Location: docs/visual-tests/

Directory structure:

docs/visual-tests/
├── baseline/           # Known-good reference screenshots
│   ├── dark-mode/
│   │   ├── code-blocks-reference.png
│   │   ├── sidebar-navigation.png
│   │   └── admin-dashboard.png
│   └── light-mode/
│       ├── code-blocks-reference.png
│       └── sidebar-navigation.png
├── comparison/         # Screenshots from feature branches
│   └── [branch-name]/
│       ├── dark-mode/
│       └── light-mode/
└── diffs/             # Generated diff images
    └── [test-name].diff.png

Naming convention: [feature]-[section].png

Tip

Always capture both dark and light mode screenshots for any visual feature. This ensures WCAG compliance and consistent UX across themes.

---

Sidebar Navigation Verification

Purpose: Verify all pages load without errors after content reorganization

Sections (68 total pages):

For Agents

18 pages across Tutorials, How-To, Reference, Explanation

For Brokers

6 pages across Tutorials, How-To, Reference, Explanation

For Admins

10 pages across How-To, Reference, Explanation

Features

9 pages (Explanations, How-Tos, Reference)

Reference

13 pages (API docs, technical specs)

Development

11 pages (developer guides)

Automated verification pattern:

// Batch verification (3-5 pages at a time)
const pages = [
  "agents/tutorials/first-week",
  "agents/how-to/respond-to-leads",
  "agents/reference/dashboard",
  "brokers/how-to/configure-brokerage",
  "admins/reference/api-key-reference"
];

for (const slug of pages) {
  await browser_navigate({
    url: `https://help.l.homestar.ink/${slug}/`
  });
  // Verify page loads without MDXError or 500
  // Check browser console for errors
}

---

Visual Regression Testing

After CSS Changes

1. Checkout baseline branch: git checkout main
2. Take baseline screenshots: Follow dark + light mode steps
3. Save to: docs/visual-tests/baseline/{dark,light}-mode/
4. Checkout feature branch: git checkout feature/new-styles
5. Take comparison screenshots: Repeat same steps
6. Save to: docs/visual-tests/comparison/[branch-name]/
7. Manual comparison: Use image diff tool or side-by-side review

After Content Changes

When modifying MDX content or adding new pages:

1. Build site: pnpm build
2. Check for broken links: Build will fail if internal links broken
3. Spot check key pages: Navigate to changed sections
4. Verify both themes: Toggle dark/light and check styling
5. Update screenshots: If visual changes intentional, retake and commit

---

Automated Testing (Future Enhancement)

Recommended tools:

Tool	Use Case	Integration
Percy	Visual regression SaaS	GitHub Actions
Playwright Visual Comparisons	Built-in screenshot diffing	CI/CD pipeline
Chromatic	Storybook integration	Component testing

Example Playwright test:

tests/visual/dark-mode.spec.js

import { test, expect } from '@playwright/test';

test('code blocks have dark backgrounds', async ({ page }) => {
  await page.goto('https://help.l.homestar.ink/reference/properties/');

  // Toggle dark mode
  await page.locator('[data-theme-toggle]').click();
  await page.waitForTimeout(300); // Theme transition

  // Compare screenshot
  await expect(page).toHaveScreenshot('dark-code-blocks.png', {
    fullPage: true,
    animations: 'disabled'
  });
});

test('code blocks have light backgrounds', async ({ page }) => {
  await page.goto('https://help.l.homestar.ink/reference/properties/');

  // Ensure light mode
  await page.locator('[data-theme-toggle]').click();
  await page.waitForTimeout(300);

  await expect(page).toHaveScreenshot('light-code-blocks.png', {
    fullPage: true
  });
});

---

Common Issues

Issue: Screenshots show different fonts

Cause: Font loading timing Solution: Add await page.waitForLoadState('networkidle') before screenshot

Issue: Dark mode not applying

Cause: Theme toggle not waited for Solution: Add explicit wait: await page.waitForTimeout(300)

Issue: Scrolling position inconsistent

Cause: Lazy loading or scroll restoration Solution: Use fullPage: true option or disable scroll restoration

Issue: Color differences between screenshots

Cause: Different color profiles or gamma settings Solution: Ensure consistent browser profile, disable GPU rasterization

---

Quick Reference Commands

# Start dev server
cd idx-docs && pnpm dev

# Build production (validates links)
pnpm build

# Run visual tests (when configured)
pnpm test:visual

# Update baseline snapshots
pnpm test:visual --update-snapshots

# Generate HTML report
pnpm test:visual --reporter=html

---

Maintenance Schedule

Task	Frequency	Owner
Review screenshots	After every CSS change	Developer
Update baselines	When design changes intentional	Design lead
Archive old screenshots	Monthly	DevOps
Audit broken screenshots	Weekly	QA

Caution

Never delete baseline screenshots from git history. Keep them for regression comparisons even after UI changes.

---

Theme-Specific Testing Checklist

When verifying visual changes, test both modes:

Dark Mode (data-theme='dark'):

• Code blocks have dark backgrounds (#1a1814)
• Syntax highlighting uses high-contrast colors
• Inline code readable against dark page background
• Sidebar badges visible with warm orange accents
• Table borders have sufficient contrast

Light Mode (default):

• Code blocks have light backgrounds (#f5f2ed)
• Syntax highlighting uses dark high-contrast text
• Inline code readable against cream page background (#faf8f4)
• Warm orange accents preserved
• No WCAG contrast violations

---

Related Documentation

• Custom CSS — Theme implementation details
• Astro Configuration — Starlight setup
• WCAG Contrast Requirements — Accessibility standards