WebAssembly Debugger Test Framework

A simplified, high-performance testing framework for WebAssembly debugging functionality in WebKit's JavaScriptCore with intelligent parallel execution.

🏗️ Architecture

Sequential Mode (Default)

Single Test Execution: One test at a time using port 12340

Framework Process (PID: 12345):
├── Main Thread (TID: 100) - coordinates execution
└── Per Test:
    ├── JSC Process (PID: 12346)
    ├── LLDB Process (PID: 12347)
    └── 4 Monitor Threads (TIDs: 101-104): JSC stdout/stderr, LLDB stdout/stderr

Total: 3 Processes, 5 Threads per test
Simple, reliable execution for debugging individual tests

Parallel Mode (--parallel)

Multi-Worker Execution: ThreadPoolExecutor with smart worker calculation

• Each worker = thread that runs one test case
• Each worker gets unique port and ProcessManager
• I/O-bound optimization: More workers than CPU cores for better utilization

Example: 3 Tests, 2 Workers

Framework Process (PID: 12345):
├── Main Thread (TID: 100) - coordinates execution
├── Worker Thread 1 (TID: 101) - TestA (Port: 12340)
│   ├── JSC Process (PID: 12346)
│   ├── LLDB Process (PID: 12347)
│   └── 4 Monitor Threads (TIDs: 103-106): JSC stdout/stderr, LLDB stdout/stderr
└── Worker Thread 2 (TID: 102) - TestB (Port: 12341)
    ├── JSC Process (PID: 12348)
    ├── LLDB Process (PID: 12349)
    └── 4 Monitor Threads (TIDs: 107-110): JSC stdout/stderr, LLDB stdout/stderr

Peak Concurrent: 5 Processes, 11 Threads
Total Used: 7 Processes, 15 Threads (when TestA finishes, Worker 1 picks up TestC)

Framework Structure

lib/
├── core/                   # Core framework components
│   ├── base.py             # BaseTestCase with pattern matching
│   ├── environment.py      # WebKit environment setup
│   ├── registry.py         # Test case registry
│   └── utils.py            # Logging with PID/TID support
├── discovery/              # Test discovery system
│   └── auto_discovery.py   # Automatic test case discovery
└── runners/                # Test execution engines
    ├── sequential.py       # Sequential test runner
    ├── parallel.py         # Parallel test execution
    └── process_manager.py  # Per-test process isolation
tests/                      # Auto-discovered test cases
├── add.py                  # WebAssembly debugging tests
└── ...                     # Additional test cases

🧪 Writing Test Cases

Create file in tests/my_test.py

from lib.core.base import BaseTestCase

class MyTestCase(BaseTestCase):
    def execute(self):
        # Setup debugging session (JSC + LLDB)
        self.setup_debugging_session_or_raise("resources/c-wasm/add/main.js")
        
        # Send LLDB commands
        self.send_lldb_command_or_raise("b main")
        self.send_lldb_command_or_raise("c")
        
        # Validate results
        self.send_lldb_command_or_raise("dis")

Auto-Discovery: Test automatically appears in --list and runs with framework. No manual registration required.

📋 Requirements

LLDB Configuration

The test framework requires a TOT (Tip of Tree) built LLDB with WebAssembly debugging support, not the system LLDB. The LLDB path is hardcoded in lib/core/environment.py:

hardcoded_lldb = "/Users/yijiahuang/git/WebKit/llvm/build/bin/lldb"

Why TOT LLDB is Required:

• System LLDB lacks the latest WebAssembly debugging features
• TOT LLDB includes WebAssembly plugin support (--plugin wasm)
• Custom LLDB build ensures compatibility with WebKit's WASM debugging protocol

Fallback Behavior:

• If the hardcoded path doesn't exist, the framework falls back to system lldb
• Tests may fail with system LLDB due to missing WebAssembly debugging capabilities

To build the required LLDB, follow the WebKit LLVM build instructions.

🚀 Quick Start

# Run all tests (sequential)
python3 test-wasm-debugger.py

# Run all tests in parallel (auto-detects optimal workers)
python3 test-wasm-debugger.py --parallel

# Run with specific number of parallel workers
python3 test-wasm-debugger.py --parallel=4

# Run specific test with verbose logging
python3 test-wasm-debugger.py --test AddTestCase --verbose

# List all available tests
python3 test-wasm-debugger.py --list

# Use specific build configuration
python3 test-wasm-debugger.py --debug    # Force Debug build
python3 test-wasm-debugger.py --release  # Force Release build