gt-stress

Gas Town pressure testing framework - stress test multi-agent workspaces to find performance limits.

Overview

gt-stress is a comprehensive pressure testing framework for Gas Town multi-agent workspaces. It progressively stress-tests the system to find performance limits, captures comprehensive metrics, and provides real-time visualization through an interactive TUI dashboard.

Features

• 🔥 Progressive load testing - Automatically finds system capacity limits
• 🤖 Hybrid agent types - Mock, simulated, and real workflow agents
• 📊 Comprehensive metrics - Timing, resource, and coordination metrics
• 🎨 Interactive TUI - Real-time dashboard with adjustable parameters
• 🔧 Flexible policies - 5 failure policies for experimentation
• 🚫 Zero LLM costs - Mocked responses for cost-effective testing
• 📈 CLI automation - Scriptable with YAML scenario files

Quick Start

# Build
go build -o gt-stress

# Run a quick test
./gt-stress run --agents 50 --duration 5m --tui

# Use a scenario
./gt-stress run scenarios/quick-test.yaml

# Analyze results
./gt-stress analyze ./results/latest

Commands

gt-stress run [scenario]    # Run stress test
gt-stress dashboard         # Launch TUI dashboard
gt-stress analyze <path>    # Analyze test results
gt-stress compare <a> <b>   # Compare two test runs

Configuration

Create a scenario file:

name: "Progressive Test"
agents:
  initial: 10
  max: 500
  ramp: "adaptive"
  mix: "30%M,50%S,20%R"

failure_policy:
  mode: "adaptive"
  target_failure_rate: 5%

metrics:
  output: "./results"
  export: ["json", "csv"]

See scenarios/ for more examples.

Agent Types

• Type M (Mock): Just spawn and exit. Fastest.
• Type S (Simulated): Lightweight file/count operations.
• Type R (Real): Full Gas Town workflows with mocked LLM.

Failure Policies

• STOP: Halt on first failure
• DEGRADE: Continue through failures
• RECOVER: Auto-retry with backoff
• ADAPTIVE: Find stable capacity points
• CONFIGURABLE: Custom rules and handlers

Development

# Run tests
go test ./...

# Build for development
go build

# Install
go install

Documentation

See DESIGN.md for complete design documentation.

License

MIT