From d3b697218773eaa5a3dd368705184726dbc0fa38 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sat, 21 Jun 2025 15:54:07 +0300
Subject: Implement headless testing framework for DS-Sim protocol simulations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Created HeadlessSimulationRunner that loads and runs simulations without GUI
- Implemented LogCapture to intercept and store all simulation logs
- Added ProtocolVerifier for flexible pattern-based log verification
- Created test runners: standard, with logs, and clean (filters GUI errors)
- Implemented tests for all non-Raft protocols
- Added DummySimulatorFrame to satisfy GUI dependencies during loading
- Created CleanHeadlessRunner that filters GUI-related errors from output
- Updated run-tests.sh script with quiet mode option
- Documented the framework architecture and usage

The framework successfully runs protocol tests and verifies behavior through
log analysis. GUI errors occur internally due to tight coupling in DS-Sim
but are filtered in quiet mode for clean output.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/testing-framework-usage.md | 88 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 docs/testing-framework-usage.md

(limited to 'docs/testing-framework-usage.md')

diff --git a/docs/testing-framework-usage.md b/docs/testing-framework-usage.md
new file mode 100644
index 0000000..9ea907d
--- /dev/null
+++ b/docs/testing-framework-usage.md
@@ -0,0 +1,88 @@
+# DS-Sim Testing Framework Usage
+
+## Overview
+
+The DS-Sim testing framework provides headless testing capabilities for protocol simulations without requiring GUI components.
+
+## Quick Start
+
+Run all protocol tests:
+```bash
+./run-tests.sh
+```
+
+## Test Runners
+
+### 1. Standard Test Runner (with logs)
+Shows test results with protocol logs:
+```bash
+java -cp target/classes testing.ProtocolTestRunnerWithLogs
+```
+
+### 2. Quiet Test Runner
+Filters out GUI-related errors for cleaner output:
+```bash
+java -cp target/classes testing.QuietProtocolTestRunner
+# or
+./run-tests.sh -q
+```
+
+### 3. Verbose Test Runner
+Shows detailed logs for debugging:
+```bash
+java -cp target/classes testing.ProtocolTestRunner -v
+# or
+./run-tests.sh -v
+```
+
+## Running Specific Tests
+
+To run tests programmatically:
+```java
+HeadlessSimulationRunner runner = new HeadlessSimulationRunner();
+runner.setPrintLogs(true); // Enable log output
+
+SimulationResult result = runner.runSimulation(
+    "saved-simulations/ping-pong.dat", 
+    2000  // Duration in ms
+);
+
+// Verify results
+ProtocolVerifier verifier = new ProtocolVerifier()
+    .expectLog("Ping-Pong.*activated")
+    .expectLog("Message sent")
+    .expectNoLog("ERROR");
+
+VerificationResult verification = verifier.verify(result.getAllLogs());
+System.out.println("Test passed: " + verification.passed());
+```
+
+## Test Coverage
+
+The framework tests all non-Raft protocols:
+- Ping-Pong
+- Ping-Pong Sturm
+- Broadcast
+- Basic Multicast
+- Reliable Multicast
+- Berkeley Time Sync
+- Internal Time Sync
+- External vs Internal Sync
+- One-Phase Commit
+- Two-Phase Commit
+- Slow Connection
+
+## Known Limitations
+
+- Some GUI-related errors may appear due to DS-Sim's tight coupling with visual components
+- These errors don't affect test functionality
+- Use quiet mode (`-q`) to filter them out
+
+## Maven Integration
+
+Run tests as part of the build:
+```bash
+mvn test
+```
+
+Note: Ensure Maven Surefire plugin is properly configured to discover test classes.
\ No newline at end of file
-- 
cgit v1.2.3