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

Advanced Options

Command Line Options

Test Files Covered

The script automatically discovers and runs these test files:

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

Browser Compatibility

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:

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:

Configuration

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

Output Example

Troubleshooting

Common Issues

1. Browser Not Found

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

2. Permission Errors

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

3. Network Timeouts

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

4. 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

Related Documentation

• Mermaid Configuration Guide
• Mermaid Quick Start
• Mermaid Examples
• Playwright Configuration
• Main Test Runner