turboplex 0.2.10

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
👀 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)

Benchmarks

Speedrun: 2 Tests

Tool	Time
pytest	12.69s
tpx (cached)	~3s

pytest:     ████████████████████████████ 12.69s
tpx:        █████ 3s (cached)

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 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)                 │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│              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)

License

MIT License - See LICENSE

Authors

Keita_Izumi

TurboPlex Team - @turbo plexus

---

🚀 The future of testing is here