Skip to content

SITE_TESTING_GUIDE.md

Latest commit

 

History

History
292 lines (208 loc) · 7.31 KB

SITE_TESTING_GUIDE.md

File metadata and controls

292 lines (208 loc) · 7.31 KB

Protocol Guide Website Testing Guide

Overview

This document describes the automated testing suite for verifying user-facing functionality on protocol-guide.com using Puppeteer browser automation.

Running Tests

# Run the full test suite
pnpm test:site

# View screenshots after testing
open test-screenshots/

Test Scenarios

1. Homepage Loads

Purpose: Verify the homepage loads successfully without errors.

Checks:

  • Page loads within timeout (30s)
  • Page title is present
  • Body content exists
  • No critical console errors

Expected Outcome: Homepage renders with content visible.

Common Issues:

  • Timeout errors (site down or slow)
  • Empty page (build/deployment issue)
  • JavaScript bundle errors

2. Search Interface

Purpose: Verify search functionality works correctly.

Checks:

  • Search input field is accessible
  • User can type query
  • Submit button exists or Enter key works
  • Response appears after submission

Expected Outcome: User can enter "cardiac arrest" and trigger search.

Common Issues:

  • Input field not found (DOM selector mismatch)
  • Search doesn't submit (event handler issue)
  • No response after search (API/backend issue)

3. Responsive Layout

Purpose: Verify site adapts to different screen sizes.

Checks:

  • Desktop viewport (1920x1080) renders correctly
  • Mobile viewport (375x667) renders correctly
  • No horizontal overflow on mobile
  • Content is readable on small screens

Expected Outcome: Site layout adapts without breaking.

Common Issues:

  • Horizontal scrolling on mobile (CSS overflow)
  • Content cut off or hidden
  • Touch targets too small on mobile

4. Network & Performance

Purpose: Verify site loads efficiently and handles network requests.

Checks:

  • Page load time under 5 seconds
  • No failed network requests (404, 500 errors)
  • Assets load successfully (CSS, JS, images)

Expected Outcome: Fast load time with no failed requests.

Common Issues:

  • Slow API responses
  • Missing assets (404 errors)
  • CDN or hosting issues

5. Basic UI Elements

Purpose: Verify essential UI components are present.

Checks:

  • Buttons are present on page
  • Links are present on page
  • Interactive elements are accessible

Expected Outcome: Page has interactive UI elements.

Common Issues:

  • Missing components (build issue)
  • Empty or broken layout

6. JavaScript Errors

Purpose: Detect runtime JavaScript errors.

Checks:

  • No uncaught exceptions
  • No console.error() calls
  • React/framework errors don't occur

Expected Outcome: No JavaScript errors in console.

Common Issues:

  • Uncaught TypeErrors (undefined properties)
  • React rendering errors
  • Third-party library errors (Supabase, tRPC, etc.)

7. Content Accessibility

Purpose: Verify basic accessibility compliance.

Checks:

  • Images have alt text attributes
  • Heading hierarchy exists (h1, h2, h3)
  • Semantic HTML structure

Expected Outcome: Content is accessible to screen readers.

Common Issues:

  • Missing alt text on images
  • No heading structure
  • Non-semantic div soup

Screenshot Locations

All screenshots are saved to /test-screenshots/ with timestamps:

test-screenshots/
  1-homepage-loads-1708123456789.png
  2-search-interface-1708123456790.png
  3-responsive-layout-1708123456791.png
  4-network-performance-1708123456792.png
  5-basic-ui-elements-1708123456793.png
  6-javascript-errors-1708123456794.png
  7-content-accessibility-1708123456795.png

Interpreting Results

Test Output Format

================================================================================
PROTOCOL GUIDE WEBSITE TEST RESULTS
================================================================================

Total Tests: 7
Passed: 6 ✓
Failed: 1 ✗
Warnings: 3

✓ PASS 1. Homepage Loads (2341ms)
  📸 /path/to/test-screenshots/1-homepage-loads-1708123456789.png

✗ FAIL 2. Search Interface (1523ms)
  Error: Timeout waiting for selector 'input[type="text"]'
  ⚠  Console: TypeError: Cannot read property 'map' of undefined
  📸 /path/to/test-screenshots/2-search-interface-error-1708123456790.png

Status Indicators

  • ✓ PASS: Test completed successfully
  • ✗ FAIL: Test threw an error and failed
  • ⚠ Warning: Test passed but with non-critical issues

Common Warnings

Warning Meaning Action
"Page load time is slow: 6234ms" Site taking >5s to load Check backend performance, CDN, or API response times
"Console: TypeError: ..." JavaScript error detected Review error in browser DevTools, check source maps
"X images missing alt text" Accessibility issue Add alt attributes to <img> tags
"No heading elements found" Accessibility issue Add semantic heading structure (h1, h2, h3)
"Could not find search input field" DOM selector mismatch Check if component structure changed

Manual Verification Checklist

After automated tests, manually verify:

  • Sign-in/auth flows work (Google, Apple)
  • State filter dropdown shows all states
  • Agency filter shows LEMSAs for selected state
  • Protocol detail page loads with content
  • Favorites/bookmarking works
  • Profile page accessible
  • Admin panel accessible (for admin users)
  • Subscription/payment flow works
  • Offline functionality (PWA)

Troubleshooting

"Chrome executable not found"

Update CHROME_PATH in scripts/test-site-v2.ts:

// macOS default
const CHROME_PATH = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';

// Alternative (if using Chromium)
const CHROME_PATH = '/Applications/Chromium.app/Contents/MacOS/Chromium';

"Timeout waiting for networkidle2"

Increase timeout in script:

const TIMEOUT = 60000; // 60 seconds

Or check if site is down:

curl -I https://protocol-guide.com

"Screenshots not generated"

Check permissions:

ls -la test-screenshots/

Manually create directory:

mkdir -p test-screenshots
chmod 755 test-screenshots

Best Practices

  1. Run tests after deployment: Verify production site after Netlify deploy
  2. Compare screenshots: Look for visual regressions between runs
  3. Monitor warnings: Even passing tests can have issues
  4. Test on staging first: Don't wait for production to catch errors
  5. Check mobile screenshots: Mobile issues often differ from desktop

Integration with CI/CD

To run in CI (GitHub Actions, Netlify, etc.):

- name: Test Production Site
  run: |
    pnpm test:site
  env:
    CI: true

For headless environments, ensure Chrome/Chromium is installed:

- name: Install Chrome
  run: |
    wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -
    sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list'
    apt-get update
    apt-get install google-chrome-stable -y

Related Documentation

Version History

  • 2026-02-18: Initial automated test suite created
  • Tests cover: homepage, search, responsive design, performance, UI, JS errors, accessibility