This project includes advanced test scripts that automatically check, update, and manage browsers before running tests, with robust timeout handling and permission-aware operations.

New NPM Scripts

Browser Management

  • npm run browsers:check - Check if all browsers are installed and working
  • npm run browsers:update - Update browsers and verify installation
  • npm run browsers:fix - Force reinstall browsers and system dependencies
  • npm run browsers:ensure-safe - Safe browser setup with permission checks

Enhanced Test Scripts

All test scripts now include the --ensure-browsers flag by default with smart timeout and permission handling:

  • npm run test:e2e - End-to-end tests with automatic browser management
  • npm run test:a11y - Accessibility tests with automatic browser management
  • npm run test:e2e:headed - Headed tests with automatic browser management
  • npm run test:e2e:debug - Debug tests with automatic browser management
  • npm run test:e2e:webkit - WebKit-specific tests with automatic browser management

Enhanced Features

🔐 Permission-Aware Operations

  • Write Permission Checking: Automatically detects if the user has sufficient permissions
  • Graceful Bypass: Skips installation if no permissions and uses existing browsers
  • Safe Mode: --skip-if-no-permissions flag for restricted environments

⏰ Timeout Protection

  • Browser Installation Timeout: 5 minutes maximum (configurable)
  • System Dependencies Timeout: 3 minutes maximum (configurable)
  • Browser Testing Timeout: 15 seconds per browser (configurable)
  • Graceful Recovery: Continues with existing browsers if timeouts occur

🛡️ Robust Error Handling

  • Process Management: Proper cleanup of hanging processes
  • Bypass on Failure: Uses existing browsers if installation fails
  • Clear Error Messages: Specific troubleshooting guidance
  • Multiple Fallback Options: Several recovery strategies

Advanced Options

Command Line Flags

# Show help
npm run playwright:ensure -- --help

# Force reinstall everything
npm run playwright:ensure -- --force

# Skip if no permissions (safe for CI/restricted environments)
npm run playwright:ensure -- --skip-if-no-permissions

# Skip system dependencies (faster, browser-only)
npm run playwright:ensure -- --skip-system-deps

# Fail on timeout instead of bypassing
npm run playwright:ensure -- --no-bypass-on-timeout

Environment-Specific Usage

# For CI/CD environments with limited permissions
npm run browsers:ensure-safe

# For development with full permissions
npm run browsers:fix

# Quick status check
npm run browsers:check

# Force update everything
npm run browsers:update

How It Works

1. Permission Detection

  • Checks write access to node_modules directory
  • Verifies browser installation locations
  • Adapts behavior based on available permissions

2. Smart Installation Strategy

  • Check Existing: First verifies if browsers already work
  • Install Only If Needed: Skips unnecessary downloads
  • Timeout Protection: Prevents hanging installations
  • Fallback Strategy: Uses existing browsers if installation fails

3. Multi-Level Recovery

  1. Primary: Install/update browsers normally
  2. Secondary: Skip system deps if they fail
  3. Tertiary: Use existing browsers if installation fails
  4. Final: Provide clear troubleshooting guidance

Troubleshooting

Permission Issues

# Safe mode for restricted environments
npm run browsers:ensure-safe

# Check current browser status
npm run browsers:check

# Manual permission fix (if you have sudo)
sudo npm run playwright:ensure

Timeout Issues

# Skip problematic system dependencies
npm run playwright:ensure -- --skip-system-deps

# Force bypass timeouts and use existing browsers
npm run test:a11y  # (automatic bypass enabled)

# Strict mode (fail on timeout)
npm run playwright:ensure -- --no-bypass-on-timeout

Installation Failures

# Force complete reinstall
npm run browsers:fix

# Check what's working
npm run browsers:check

# Use existing browsers only
npm run playwright:ensure -- --skip-if-no-permissions

Error Messages and Solutions

Error Message Solution
“Insufficient permissions detected” Use npm run browsers:ensure-safe
“Browser installation timed out” Use --skip-system-deps or check network
“No working browsers found” Try npm run browsers:fix
“System dependencies failed” Normal in restricted environments, tests may still work

Performance Features

  • Skip Redundant Operations: Only installs if browsers aren’t working
  • Parallel Verification: Tests all browsers simultaneously
  • Smart Caching: Leverages Playwright’s built-in caching
  • Quick Status Checks: Fast browser verification without installation

Security Features

  • Permission Validation: Checks before attempting installations
  • Process Isolation: Proper cleanup of child processes
  • Timeout Protection: Prevents resource exhaustion
  • Safe Defaults: Conservative settings for production environments

Technical Details

The browser management system consists of:

  • scripts/check-browsers.js - Browser status verification with timeout handling
  • scripts/ensure-browsers.js - Smart installer with permission awareness
  • scripts/test-runner.js - Enhanced test runner with automatic browser management
  • scripts/test-webkit.js - WebKit-specific handling with fallbacks

Configuration Constants

TIMEOUT_BROWSER_INSTALL = 300000; // 5 minutes
TIMEOUT_SYSTEM_DEPS = 180000; // 3 minutes
TIMEOUT_BROWSER_TEST = 15000; // 15 seconds

Permission Checking

  • Validates write access to installation directories
  • Detects WSL/Linux permission restrictions
  • Provides fallback strategies for limited environments

Timeout Handling

  • Process-level timeouts with proper cleanup
  • Graceful degradation on timeout
  • Clear timeout notifications with next steps