Metadata-Version: 2.4
Name: turboplex
Version: 0.2.9
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Requires-Dist: pytest>=7.0
Requires-Dist: pytest-xdist>=3.0
Requires-Dist: mcp
License-File: LICENSE
Summary: High Performance Test Engine - Rust + Python
Author: Keita_Izumi
Requires-Python: >=3.10
Description-Content-Type: text/markdown

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

**English** | [Español](README.es.md)

<p align="center">
  <img src="https://img.shields.io/badge/Rust-DEA584?style=for-the-badge&logo=rust&logoColor=white" alt="Rust">
  <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License">
</p>

## 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

```bash
# Install from PyPI
pip install turboplex

# Verify the installation
tpx --help
```

```bash
# Clone the repository (dev)
cd turboplex

# Install in development mode
pip install -e .

# Verify the installation
tpx --help
```

## Quick Start

### Basic Execution

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

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

# Auto-discover tests
tpx
```

### Watch Mode (TDD Development)

```bash
# 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.).

```bash
tpx --compat --path tests/
```

### MCP Server (IDE Integration)

```bash
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` to force the Python interpreter used for subprocesses (Windows robustness).
  - `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)

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

```bash
# 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

```toml
[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

```json
{
  "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 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](https://github.com/IzumiKeita/turboplex)

---

<p align="center">
  🚀 <em>The future of testing is here</em>
</p>

