Mermaid Test Runner

This document describes the dedicated test runner for Mermaid diagram functionality in the MIJUG .NET workspace.

Overview

The scripts/test-mermaid-diagrams.js script provides a specialized test runner that focuses exclusively on Mermaid diagram rendering and functionality. It automatically discovers all mermaid-related test files and provides flexible browser testing options.

Features

Automatic Test Discovery: Finds all mermaid-related test files in the e2e directory
Multi-Browser Support: Tests with Chromium, Firefox, and WebKit
Browser Management: Automatic browser installation and verification
Flexible Options: Headed/headless modes, debug mode, custom worker counts
Error Handling: Robust error handling with helpful messages
Cross-Platform: Works on Linux, macOS, and Windows

Usage

Basic Commands

# Run all mermaid tests with default settings (Chromium, headless)
npm run test:mermaid

# Run with browser UI visible (helpful for debugging)
npm run test:mermaid:headed

# Run in debug mode (step-by-step execution)
npm run test:mermaid:debug

# Run with Firefox browser
npm run test:mermaid:firefox

Advanced Options

# Run with specific browser and options
node scripts/test-mermaid-diagrams.js --project=webkit --workers=2 --verbose

# Ensure browsers are installed first
node scripts/test-mermaid-diagrams.js --ensure-browsers

# Run in headed mode with debug
node scripts/test-mermaid-diagrams.js --headed --debug

# Get help and see all available options
node scripts/test-mermaid-diagrams.js --help

Command Line Options

Option	Description	Example
`--ensure-browsers`	Install browsers before testing	`--ensure-browsers`
`--headed`	Run with browser UI visible	`--headed`
`--debug`	Step-by-step debug mode	`--debug`
`--project=<name>`	Specify browser (chromium, firefox, webkit)	`--project=firefox`
`--workers=<num>`	Number of parallel workers (default: 1)	`--workers=2`
`--verbose`	Enable verbose output	`--verbose`
`--help`	Show help message	`--help`

Test Files Covered

The script automatically discovers and runs these test files:

e2e/mermaid-basic-visual.spec.ts
- Tests basic mermaid diagram rendering
- Validates SVG generation and visual elements
e2e/mermaid-default-layout.spec.ts
- Tests mermaid rendering in default page layout
- Validates sequence diagrams and syntax error handling
e2e/mermaid-diagrams-visual.spec.ts
- Tests visual diagram sample page
- Validates multiple diagram types and SVG content
e2e/mermaid-documentation.spec.ts
- Tests documentation pages
- Validates quick start, configuration guide, and examples

Browser Compatibility

Browser	Support Level	Notes
Chromium	✅ Full	Default browser, fastest execution
Firefox	✅ Full	Good compatibility, slightly slower
WebKit	✅ Full	Safari engine, best for macOS testing

Error Handling

The script provides comprehensive error handling:

Browser Detection: Automatically detects available browsers
Fallback Support: Falls back to available browsers if requested browser isn’t available
Installation Help: Guides users to install missing browsers
Clear Messages: Provides helpful error messages and suggestions

Integration with CI/CD

The script is designed to work in continuous integration environments:

# Example GitHub Actions usage
- name: Run Mermaid Tests
  run: npm run test:mermaid

# With specific browser
- name: Run Mermaid Tests (Firefox)
  run: npm run test:mermaid:firefox

# With browser installation
- name: Run Mermaid Tests (All Browsers)
  run: |
    npm run test:mermaid -- --ensure-browsers --project=chromium
    npm run test:mermaid -- --project=firefox
    npm run test:mermaid -- --project=webkit

Performance Considerations

Single Worker Default: Uses 1 worker by default for stability
Network Idle: Waits for network idle state before testing
Timeout Handling: Includes appropriate timeouts for browser operations
Resource Cleanup: Properly cleans up browser instances

Debugging

For debugging mermaid rendering issues:

# Run in debug mode with browser UI
npm run test:mermaid:debug

# Run specific test file in headed mode
node scripts/test-mermaid-diagrams.js --headed --project=chromium e2e/mermaid-basic-visual.spec.ts

# Enable verbose output for detailed logs
node scripts/test-mermaid-diagrams.js --verbose --headed

Configuration

The script respects the Playwright configuration in playwright.config.ts but allows overrides via command line arguments.

Output Example

🎨 Mermaid Diagrams Test Runner Starting...
ℹ️  🔧 Ensuring browsers are installed...
✅ All browsers are ready for testing!
ℹ️  📊 Browser Engine Summary:
ℹ️    🎯 (selected) chromium - Available
ℹ️    ✅ firefox - Available
ℹ️    ✅ webkit - Available
ℹ️  🚀 Starting Mermaid diagram tests...
ℹ️  Found 4 mermaid test files:
🔍   - e2e/mermaid-basic-visual.spec.ts
🔍   - e2e/mermaid-default-layout.spec.ts
🔍   - e2e/mermaid-diagrams-visual.spec.ts
🔍   - e2e/mermaid-documentation.spec.ts

Running 7 tests using 1 worker
  ✓  All tests passed
✅ ✅ All Mermaid tests completed successfully!

Troubleshooting

Common Issues

Browser Not Found

# Solution: Install browsers
npm run test:mermaid -- --ensure-browsers

Permission Errors

# Solution: Run with proper permissions or use skipIfNoPermissions
node scripts/test-mermaid-diagrams.js --ensure-browsers --skip-if-no-permissions

Network Timeouts

# Solution: Increase timeout or check network connectivity
node scripts/test-mermaid-diagrams.js --workers=1

iNotify Watches Limit Exceeded (Linux)

Error: Listen::Error::INotifyMaxWatchesExceeded: Unable to monitor directories for changes because iNotify max watches exceeded

Symptoms: Jekyll server fails to start with file watching errors, preventing the test server from running.

Solution: Increase the iNotify watches limit on Linux systems:
```
# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase limit permanently (requires sudo)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Verify the change
cat /proc/sys/fs/inotify/max_user_watches
```
Alternative temporary fix:
```
# Temporary increase (until reboot)
sudo sysctl fs.inotify.max_user_watches=524288
```
Background: This issue occurs when Jekyll tries to watch too many files for changes. The default Linux limit is typically 8,192 watches, but large projects with many files can exceed this limit. Setting it to 524,288 provides ample headroom for most development scenarios.

Future Enhancements

Potential improvements to the script:

Parallel Browser Testing: Run multiple browsers simultaneously
Visual Regression Testing: Screenshot comparison for diagram rendering
Performance Metrics: Measure diagram rendering performance
Custom Test Patterns: Allow custom glob patterns for test discovery
Report Generation: Generate detailed HTML reports
Integration Testing: Test mermaid with different Jekyll configurations