turboplex 0.3.0

High Performance Test Engine - Rust + Python

TurboPlex (tpx) — The Test Orchestration Engine for the AI Era

English | Español

Why TurboPlex?

4x faster than Pytest for test execution. The orchestration engine built for the AI era.

Value Proposition

Feature	Description
⚡ 4x Speed	Parallel execution with smart caching (12s → 3s)
🦀 Rust Core	Static analysis and memory management with minimal overhead
🤖 M2M Protocol	Generates .tplex_report.json with AI-actionable errors
� AI Analysis	--analyze command categorizes failures for debugging at scale
� Watch Mode	Auto-reload when you save .py files

Installation

# Install from PyPI
pip install turboplex

# Verify the installation
tpx --help

# Clone the repository (dev)
cd turboplex

# Install in development mode
pip install -e .

# Verify the installation
tpx --help

Quick Start

Basic Execution

# Single test
tpx --path tests/test_simple.py

# Multiple directories
tpx --path tests/ --path tests/integration/

# Auto-discover tests
tpx

Watch Mode (TDD Development)

# Run and watch changes in real time
tpx --watch --path tests/

Pytest Compatibility Mode (--compat)

Use this when your suite relies on complex pytest fixtures (conftest.py, client, db, etc.).

tpx --compat --path tests/

Light Collect Mode (--light)

For projects with heavy conftest.py initialization (e.g., database migrations, schema creation), use --light to skip conftest loading during test discovery. This can reduce discovery time from minutes to seconds.

# Fast discovery for projects with heavy conftest.py
tpx --compat --light

# Or set the environment variable
export TPX_MCP_LIGHT_COLLECT=1  # Linux/Mac
set TPX_MCP_LIGHT_COLLECT=1     # Windows
tpx --compat

When to use:

• Your conftest.py initializes databases or runs migrations on import
• Test discovery takes more than 10 seconds
• You're using TurboPlex MCP with an IDE (Windsurf, Cursor, etc.)

MCP Server (IDE Integration)

tpx mcp

Notes:

• For robustness, TurboPlex isolates tool payloads in JSON files (--out-json) to prevent stdout pollution.
• Subprocesses enforce UTF-8 (PYTHONUTF8=1, PYTHONIOENCODING=utf-8, PYTHONUNBUFFERED=1) to avoid Windows encoding issues.
• Timeouts are structured and configurable via environment variables:
  • TPX_PYTHON_EXE - Force specific Python interpreter (useful for venvs on Windows).
  • TPX_MCP_LIGHT_COLLECT=1 - Skip conftest.py during discovery (for projects with heavy DB initialization).
  • TPX_MCP_DEBUG=1 - Enable debug tracing to stderr (shows commands, Python used, etc.).
  • TPX_MCP_STDOUT_MODE - redirect (default) or failfast for JSON-RPC guarding.
  • TPX_MCP_TURBOPLEX_COLLECT_TIMEOUT_S (default 120)
  • TPX_MCP_TURBOPLEX_RUN_TIMEOUT_S (default 60)
  • TPX_MCP_PYTEST_COLLECT_TIMEOUT_S or TPX_PYTEST_COLLECT_TIMEOUT_S (default 120)
  • TPX_MCP_PYTEST_RUN_TIMEOUT_S or TPX_PYTEST_RUN_TIMEOUT_S (default 60)

Example MCP Configuration (Windsurf/Cursor):

{
  "mcpServers": {
    "tpx": {
      "command": "tpx",
      "args": ["mcp"],
      "env": {
        "TPX_PYTHON_EXE": "/path/to/venv/bin/python",
        "TPX_MCP_LIGHT_COLLECT": "1",
        "TPX_MCP_DEBUG": "1"
      }
    }
  }
}

Tools exposed over MCP:

• ping
• turboplex_version
• discover(paths=None, compat=False)
• run(selection, compat=False, max_workers=None)
• get_report(path=None)

Integration with AI Agents

# INSTRUCTION FOR YOUR AI AGENT:
# If you detect a .tplex_report.json file in the project,
# read it immediately and propose an automatic fix.

# The file contains:
# - Exact error
# - Failure line
# - Code context (5 lines before and after)

AI-Driven Test Analysis (--analyze)

For large test suites with hundreds of failures, TurboPlex provides automatic error categorization and actionable recommendations. Tested on real-world production suites (~200 tests, ~3.2MB of failure data).

# Run tests with full JSONL report generation
tpx --path tests/

# Analyze the generated report
tpx --analyze

Example Output:

════════════════════════════════════════════════════════════
          TurboPlex Analysis Report
════════════════════════════════════════════════════════════

📊 Summary
   Total:  199
   Passed: 35
   Failed: 164
   Rate:   17.6%

🚨 Critical Issues
   • 45 tests have database connectivity issues
   • 12 tests have import errors - dependencies may be missing

📋 Error Categories
   [45] AuthError: Expected 200 got 403 - Authorization failures
   [32] DatabaseError: Unique constraint violation
   [28] FixtureError: Fixture setup failed
   [20] AssertionError: Creation status mismatch
   [15] ImportError: Missing module

💡 Top Recommendations
   1. Priority 45: Check authentication fixtures - ensure tests have valid credentials
   2. Priority 32: Implement database cleanup between tests or use unique identifiers
   3. Priority 28: Review fixture dependencies and ensure proper setup/teardown

Generated Files:

• turboplex_full_report.json — Complete JSONL report with full error context (traceback, locals, diff)
• Automatic categorization: Database errors, Auth failures, Import issues, Fixture problems
• AI-ready JSON output for automated debugging pipelines

Speedrun: Production Suite (~200 tests)

Tool	Time	per test
pytest	~340s	~1.7s
tpx (cold)	~180s	~0.9s
tpx (cached)	~25s	~0.13s

pytest (cold):  ████████████████████████████████████████ 340s
tpx (cold):     ██████████████████████ 180s (2x faster)
tpx (cached):   ███ 25s (14x faster, 82% cache hit)

🖥️ Tested on:

• CPU: Ryzen 7 5700X3D (8C/16T)
• RAM: 16GB DDR4 @ 3600MHz
• Storage: Crucial P3 NVMe Gen3 (1TB)

Per-Test Comparison

Metric	pytest	tpx
Time per test	~6s	~1.5s
Caching	No	Yes (SHA-256)
M2M Report	No	Yes (.tplex_report.json)

Configuration

turbo_config.toml File

[execution]
max_workers = 8
default_timeout_ms = 30000
cache_enabled = true

[python]
enabled = true
interpreter = "python"
module = "turboplex_py"
test_paths = ["tests"]
project_path = "."

Cache

The cache is stored in .turboplex_cache/ and is automatically invalidated when test files change (SHA-256 hash) or when the runtime fingerprint changes (Python version, dependency lock hash, PYTHONPATH, execution flags).

API for AI Agents

.tplex_report.json Format

{
  "timestamp": "2026-03-28 14:17:49",
  "total_tests": 1,
  "failed_count": 1,
  "failures": [
    {
      "test": "test_fiscal_year_close_logic",
      "file": "tests/test_accounting_close.py",
      "line": 42,
      "error": "parameter 'db' has no @fixture and no default",
      "context": [
        "    38: def test_fiscal_year_close_logic(db):",
        "    39:     # Arrange",
        "    40:     year = 2024",
        ">>> 41:     result = close_year(db, year)",
        "    42:     assert result.success"
      ]
    }
  ]
}

Commands

Command	Description
tpx	Auto-discover and run tests
tpx --path ./tests	Run tests in a directory
tpx --watch	Watch mode with auto-reload
tpx --compat	Delegate discovery/execution to pytest for fixture-heavy suites
tpx --compat --light	Fast discovery mode (skips conftest.py loading)
tpx --analyze	Analyze test failures and categorize errors (requires turboplex_full_report.json)
tpx mcp	Start the MCP server over stdio for IDE integration
tpx --help	Show help

Architecture

┌─────────────────────────────────────────────────────┐
│                    tpx (Rust)                        │
├─────────────────────────────────────────────────────┤
│  • Test discovery                                   │
│  • SHA-256 caching                                  │
│  • Parallel execution (Rayon)                       │
│  • Watch mode (notify)                              │
│  • M2M report (.tplex_report.json)                  │
│  • JSONL reports (turboplex_full_report.json)       │
│  • AI Analysis (--analyze)                          │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│              turboplex_py (Python)                  │
├─────────────────────────────────────────────────────┤
│  • collector.py - Test discovery                    │
│  • runner.py - Test runner                          │
│  • fixtures.py - @fixture system                    │
│  • markers.py - skip, skipif                        │
└─────────────────────────────────────────────────────┘

Files Excluded from the Repository (.gitignore)

This project ignores generated files and local configuration to keep the repository lightweight, reproducible, and free of sensitive data.

• Build artifacts and caches (e.g., target/, **/target/, .cache/)
• Temporary files and logs (*.tmp, *.log, *.swp)
• Local IDE/OS configuration (e.g., .vscode/, .idea/, Thumbs.db, .DS_Store)
• Python local environments and metadata (e.g., .venv/, __pycache__/, *.egg-info/)
• Environment files with secrets or local configuration (.env, .env.*)
• Web tooling dependencies and outputs if applicable (node_modules/, dist/, build/)
• TurboPlex-generated caches and reports (.turboplex_cache/, .tplex_report.json, turboplex_full_report.json)

License

MIT License - See LICENSE

Authors

Keita_Izumi

TurboPlex Version: 0.3.0 - @turbo plexus

---

🚀 The future of testing is here