This document describes the browser compatibility testing system for MIJUG .NET, which validates browser version detection and ensures the browserslist configuration is being respected.

Overview

The browser compatibility test suite simulates different browser versions to verify:

  1. Browser Version Detection: Accurate detection of browser name and version
  2. Browser Age Calculation: Appropriate age display with warnings for outdated browsers
  3. Browserslist Compliance: Respect for the project’s browserslist configuration
  4. User Experience: Proper warning display for unsupported browsers

Browserslist Configuration

The project’s package.json defines supported browsers:

{
  "browserslist": [
    "defaults",
    "last 2 versions",
    "> 1%",
    "IE 11",
    "Chrome >= 60",
    "Firefox >= 55",
    "Safari >= 12",
    "Edge >= 16"
  ]
}

Test Categories

1. Modern Browser Detection

Tests that current, up-to-date browsers are detected correctly:

  • Chrome 128+: Should show as “recent” or with specific age
  • Firefox 129+: Should show as “recent” or with specific age
  • Safari 18+: Should show as “recent” or with specific age
  • Edge 128+: Should show as “recent” or with specific age

2. Supported Browser Detection

Tests browsers within the browserslist range:

  • Chrome 80: Should be marked as supported but older
  • Firefox 75: Should be marked as supported but older
  • Safari 14: Should be marked as supported but older
  • Edge 83: Should be marked as supported but older

3. Unsupported Browser Warning

Tests browsers below the browserslist threshold:

  • Chrome 58: Should show “Age unknown (Older version)” warning
  • Firefox 52: Should show age warning
  • Safari 11: Should show age warning
  • Edge 15: Should show age warning

4. Future Browser Handling

Tests very new browsers not in the release database:

  • Chrome 150: Should show “Very recent ✨ (Newer than our database)”
  • Firefox 150: Should show “Very recent ✨ (Newer than our database)”

Running the Tests

Quick Test Commands

# Run all browser compatibility tests
npm run test:browser-compat

# Run in headed mode (visible browser)
npm run test:browser-compat:headed

# Force rebuild site before testing
npm run test:browser-compat:build

# Run specific test pattern
npx playwright test e2e/browser-compatibility.spec.ts --grep "Chrome"

Manual Test Script

# Run the custom test script with options
node scripts/test-browser-compatibility.js
node scripts/test-browser-compatibility.js --build --headed

Individual Test Cases

# Test modern browser detection
npx playwright test --grep "should detect modern Chrome"

# Test old browser warnings
npx playwright test --grep "should warn about unsupported"

# Test future browser handling
npx playwright test --grep "should handle very new browser"

# Test browserslist compliance
npx playwright test --grep "Browserslist Configuration"

Expected Test Results

✅ Passing Scenarios

  1. Modern Browsers: Detected with appropriate age indicators (✨, days/months old)
  2. Supported Browsers: Marked as supported with accurate age calculation
  3. Old Browsers: Show warnings (⚠️ Outdated, ⚡ Consider updating)
  4. Future Browsers: Handle gracefully with “Very recent” indicators
  5. Accessibility: All browser info elements properly labeled and accessible

❌ Failing Scenarios (Expected Warnings)

  1. Chrome < 60: Should fail browserslist validation
  2. Firefox < 55: Should fail browserslist validation
  3. Safari < 12: Should fail browserslist validation
  4. Edge < 16: Should fail browserslist validation

Browser Info Display

The about page displays comprehensive browser information:

Browser Details

  • Browser Name: Chrome, Firefox, Safari, Edge, Opera
  • Browser Version: Major.minor version number
  • Browser Age: Age with visual indicators
  • Platform: Operating system
  • Language: Browser language setting
  • Cookies: Whether cookies are enabled

Visual Age Indicators

  • ✨ Recent: Less than 30 days old
  • ⚡ Consider updating: 6+ months old
  • ⚠️ Outdated: 1+ year old
  • 🔍 Age unknown: Not in release database

Test Architecture

Mock User Agents

The tests use realistic user agent strings for different browser versions:

const mockUserAgents = {
  chromeModern: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36',
  chromeOld: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36',
  // ... more user agents
};

Release Date Database

The browser age calculation uses a database of major version release dates:

const releaseDates = {
  Chrome: {
    128: '2024-08-20', 127: '2024-07-16', // ...
  },
  Firefox: {
    129: '2024-08-06', 128: '2024-07-09', // ...
  },
  // ... more browsers
};

Accessibility Testing

The test suite includes accessibility validation:

  • WCAG 2.1 AA Compliance: Using axe-core for automated a11y testing
  • Proper Labeling: All browser info elements have associated labels
  • Keyboard Navigation: Cache busting shortcuts work properly
  • Screen Reader Support: Information is properly structured

Integration with Jekyll

The tests validate Jekyll-specific features:

  • Cache Busting: Meta tags and JavaScript cache versioning
  • Development Mode: Additional debug information display
  • Environment Variables: Proper handling of Jekyll environments
  • Build Verification: Ensures Jekyll site builds before testing

Debugging Failed Tests

Common Issues

  1. Timeout Errors: Usually indicates the about page isn’t loading properly 
    # Check if Jekyll site exists
ls -la docs/_site/about/index.html

# Rebuild if needed
npm run build:jekyll:drafts
  2. Version Mismatch: Test expectations don’t match detected versions 
    # Check what version is actually detected
npx playwright test --grep "browser info" --reporter=line
  3. URL Construction: File path issues in different environments 
    # Set explicit base URL
BASE_URL="file://$(pwd)/docs/_site" npx playwright test

Debug Mode

Run tests with debug logging:

# Enable debug output
DEBUG=playwright:* npx playwright test e2e/browser-compatibility.spec.ts

# Run single test with trace
npx playwright test --trace on --grep "should detect modern Chrome"

Continuous Integration

The browser compatibility tests run as part of the CI pipeline:

# .github/workflows/test.yml
- name: Run Browser Compatibility Tests
  run: |
    npm run build:jekyll:drafts
    npm run test:browser-compat

Future Enhancements

  1. Dynamic Release Dates: Fetch current browser release schedules
  2. Custom Warnings: Site-specific compatibility messages
  3. Performance Metrics: Browser performance testing
  4. Real Device Testing: Cross-platform validation
  5. Analytics Integration: Track visitor browser distributions

Last Updated: August 4, 2025
Test Coverage: 95%+ browser compatibility scenarios
Supported Browsers: Chrome 60+, Firefox 55+, Safari 12+, Edge 16+