leptos-shadcn-ui/docs/testing/WASM_TESTING_GUIDE.md

🧪 Enhanced WASM Browser Testing Guide

Comprehensive WASM Testing Infrastructure for leptos-shadcn-ui

📋 Overview

Our enhanced WASM browser testing infrastructure provides comprehensive validation of WebAssembly functionality across all supported browsers, ensuring reliable performance and compatibility for production-ready components.

🎯 Key Features

• Cross-Browser Testing: Chrome, Firefox, Safari, Mobile Chrome, Mobile Safari
• Performance Monitoring: Initialization time, memory usage, interaction latency
• Memory Management: Leak detection and memory pressure testing
• Error Handling: Graceful error recovery and failure scenarios
• Bundle Analysis: WASM bundle size and loading optimization
• Automated Reporting: HTML, JSON, and Markdown test reports

🚀 Quick Start

Basic Usage

# Run all WASM tests with default settings
make test-wasm

# Run tests on specific browsers
make test-wasm-browsers BROWSERS=chromium,firefox

# Run tests in headed mode (see browser windows)
make test-wasm-headed

# Run tests in parallel for faster execution
make test-wasm-parallel

# Run tests with verbose output
make test-wasm-verbose

Advanced Usage

# Run specific test scenarios
./scripts/run-wasm-tests.sh -s basic-initialization,memory-management

# Run on specific browsers with custom settings
./scripts/run-wasm-tests.sh -b chromium,firefox -H -v

# Run in parallel without generating reports
./scripts/run-wasm-tests.sh -p -r

🏗️ Test Architecture

Test Structure

tests/e2e/
├── wasm-browser-testing.spec.ts    # Main WASM test suite
├── wasm-performance-monitor.ts     # Performance monitoring utility
├── wasm-test-config.ts            # Configuration management
└── wasm-test-results/             # Test results and reports

Test Categories

1. WASM Initialization & Loading

• ✅ Successful initialization across browsers
• ✅ Error handling for failed loads
• ✅ Initialization time measurement
• ✅ Loading state management

2. Memory Management

• ✅ Memory leak detection
• ✅ Memory pressure handling
• ✅ Memory usage monitoring
• ✅ Garbage collection validation

3. Cross-Browser Compatibility

• ✅ Consistent behavior across browsers
• ✅ Browser-specific feature detection
• ✅ WASM capability validation
• ✅ Fallback mechanism testing

4. Performance Monitoring

• ✅ Performance benchmark validation
• ✅ Load time measurement
• ✅ Interaction latency testing
• ✅ Performance regression detection

5. Error Handling & Recovery

• ✅ Runtime error handling
• ✅ Failure recovery testing
• ✅ Error boundary validation
• ✅ Graceful degradation

6. Bundle Analysis

• ✅ WASM bundle size validation
• ✅ Loading efficiency testing
• ✅ Network request monitoring
• ✅ Resource optimization

📊 Performance Benchmarks

Default Thresholds

Metric	Threshold	Description
Initialization Time	5 seconds	Maximum time for WASM to initialize
First Paint	3 seconds	Maximum time to first visual content
First Contentful Paint	4 seconds	Maximum time to meaningful content
Interaction Latency	100ms	Maximum average interaction response time
Memory Increase	50%	Maximum memory increase during operations

Browser-Specific Thresholds

Browser	Init Time	First Paint	Notes
Chrome	5s	3s	Standard thresholds
Firefox	6s	3s	Slightly more time for initialization
Safari	7s	3.5s	More conservative thresholds
Mobile Chrome	8s	4s	Mobile-optimized thresholds
Mobile Safari	10s	5s	Most conservative for mobile Safari

🔧 Configuration

Environment Variables

# Performance thresholds
export WASM_MAX_INIT_TIME=5000
export WASM_MAX_FIRST_PAINT=3000
export WASM_MAX_FCP=4000
export WASM_MAX_INTERACTION_LATENCY=100
export WASM_MAX_MEMORY_INCREASE=50

# Browser selection
export WASM_ENABLED_BROWSERS="chromium,firefox,webkit"

# Scenario selection
export WASM_ENABLED_SCENARIOS="basic-initialization,memory-management"

# Reporting
export WASM_OUTPUT_DIR="test-results/wasm-tests"
export WASM_GENERATE_HTML_REPORT=true
export WASM_GENERATE_JSON_REPORT=true
export WASM_GENERATE_MARKDOWN_REPORT=true

Custom Configuration

Create a custom configuration file:

// wasm-test-config.custom.ts
import { WASMTestConfig } from './wasm-test-config';

export const customConfig: WASMTestConfig = {
  performance: {
    maxInitializationTime: 3000, // Stricter for CI
    maxFirstPaint: 2000,
    maxFirstContentfulPaint: 3000,
    maxInteractionLatency: 50,
    maxMemoryIncrease: 25,
  },
  browsers: {
    chromium: { enabled: true, timeout: 20000, retries: 1 },
    firefox: { enabled: false }, // Skip Firefox in CI
    webkit: { enabled: true, timeout: 25000, retries: 2 },
  },
  // ... other settings
};

📈 Test Reports

Report Types

1. HTML Reports: Interactive test results with screenshots and videos
2. JSON Reports: Machine-readable data for CI/CD integration
3. Markdown Reports: Human-readable summaries with performance metrics

Report Structure

test-results/wasm-tests/
├── wasm-test-report-20241213_143022.md    # Main summary report
├── chromium/                              # Browser-specific results
│   ├── results.json
│   ├── results.html
│   └── screenshots/
├── firefox/
│   ├── results.json
│   ├── results.html
│   └── screenshots/
└── webkit/
    ├── results.json
    ├── results.html
    └── screenshots/

Sample Report

# WASM Browser Testing Report

**Generated**: 2024-12-13T14:30:22Z
**Test Configuration**:
- Browsers: chromium,firefox,webkit
- Scenarios: basic-initialization,memory-management,performance-monitoring
- Headless Mode: true
- Parallel Execution: false

## Test Results Summary

### chromium
- **Passed**: 15
- **Failed**: 0
- **Skipped**: 0

### firefox
- **Passed**: 14
- **Failed**: 1
- **Skipped**: 0

### webkit
- **Passed**: 13
- **Failed**: 2
- **Skipped**: 0

🐛 Debugging

Common Issues

1. WASM Initialization Failures

# Check WASM target installation
rustup target list --installed | grep wasm32-unknown-unknown

# Reinstall WASM target if missing
rustup target add wasm32-unknown-unknown

# Check browser console for errors
make test-wasm-headed

2. Performance Threshold Failures

# Run with verbose output to see detailed metrics
make test-wasm-verbose

# Check specific browser performance
./scripts/run-wasm-tests.sh -b chromium -v

3. Memory Issues

# Monitor memory usage during tests
./scripts/run-wasm-tests.sh -s memory-management -v

# Check for memory leaks
./scripts/run-wasm-tests.sh -s memory-management -H

Debug Mode

# Run tests in debug mode with browser inspector
pnpm playwright test tests/e2e/wasm-browser-testing.spec.ts --debug

# Run specific test in debug mode
pnpm playwright test tests/e2e/wasm-browser-testing.spec.ts --debug --grep "should initialize WASM successfully"

🔄 CI/CD Integration

GitHub Actions

name: WASM Browser Testing

on: [push, pull_request]

jobs:
  wasm-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          target: wasm32-unknown-unknown
          
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: |
          pnpm install
          pnpm playwright install
          
      - name: Run WASM tests
        run: make test-wasm
        env:
          WASM_MAX_INIT_TIME: 8000  # More lenient in CI
          WASM_ENABLED_BROWSERS: "chromium,firefox"
          
      - name: Upload test results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: wasm-test-results
          path: test-results/wasm-tests/

Local Development

# Pre-commit hook for WASM testing
echo '#!/bin/sh
make test-wasm-browsers BROWSERS=chromium
' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

📚 Best Practices

1. Test Strategy

• Run WASM tests on every component change
• Use parallel execution for faster feedback
• Monitor performance trends over time
• Test on multiple browsers before releases

2. Performance Optimization

• Set realistic performance thresholds
• Monitor memory usage patterns
• Optimize WASM bundle sizes
• Use browser-specific optimizations

3. Error Handling

• Test error scenarios thoroughly
• Implement graceful fallbacks
• Monitor error rates in production
• Document known limitations

4. Maintenance

• Update browser versions regularly
• Review and adjust performance thresholds
• Monitor test execution times
• Keep dependencies up to date

🎯 Future Enhancements

Planned Features

• Visual Regression Testing: Automated screenshot comparison
• Performance Budgets: Enforce performance thresholds in CI
• Real Device Testing: Test on actual mobile devices
• WASM Profiling: Detailed performance profiling integration
• Automated Optimization: AI-powered performance recommendations

Integration Opportunities

• Storybook Integration: Component story testing
• Design System Testing: Visual consistency validation
• API Testing: Backend integration testing
• Load Testing: High-traffic scenario testing

📞 Support

For issues or questions about WASM testing:

1. Check the troubleshooting section
2. Review test reports for specific failures
3. Run tests in debug mode for detailed analysis
4. Check browser console for error messages
5. Verify WASM target installation and browser compatibility

---

Last Updated: December 2024
Version: 1.0.0
Maintainer: leptos-shadcn-ui Team