testx-cli 0.1.1

testx is a universal test runner that auto-detects your project's language and framework, runs your tests, and displays clean, unified output. Zero configuration required.

Why testx?

Features

• Auto-detection — Identifies language and test framework from project files
• 11 languages — Rust, Go, Python, JavaScript/TypeScript, Java, C/C++, Ruby, Elixir, PHP, .NET, Zig
• Multiple output formats — Pretty (default), JSON, JUnit XML, TAP
• CI sharding — Split tests across CI nodes with --partition slice:1/4 or hash:2/3
• Stress testing — Run tests N times to find flaky tests with testx stress
• Impact analysis — Only run tests affected by recent git changes with --affected
• Smart caching — Skip re-running tests when nothing changed with --cache
• Interactive picker — Fuzzy-search and pick specific tests with testx pick
• Watch mode — Re-run tests on file changes
• Retry logic — Automatically retry failing tests
• Parallel execution — Run multiple test suites concurrently
• Coverage integration — LCOV, Cobertura, JaCoCo, Go coverage
• Plugin system — Custom adapters, reporter plugins, shell hooks
• History tracking — Track test health scores, flaky tests, and trends over time
• Monorepo support — Scan and test all projects in a workspace with testx workspace

Supported Languages

Installation

From crates.io

cargo install testx-cli

From source

cargo install --path .

From releases

Download a prebuilt binary from the releases page.

Shell completions

# Bash
testx completions bash > ~/.local/share/bash-completion/completions/testx

# Zsh
testx completions zsh > ~/.local/share/zsh/site-functions/_testx

# Fish
testx completions fish > ~/.config/fish/completions/testx.fish

# PowerShell
testx completions powershell >> $PROFILE

Quick Start

# Run tests in the current directory
testx

# Run tests in a specific project
testx -p /path/to/project

# Detect framework without running tests
testx detect

# Pass extra arguments to the underlying runner
testx -- --filter my_test

Usage

Output formats

testx                    # Pretty terminal output (default)
testx -o json            # Machine-readable JSON
testx -o junit > report.xml  # JUnit XML for CI
testx -o tap             # Test Anything Protocol

CI sharding

Split tests across parallel CI jobs:

# Slice-based (deterministic, ordered)
testx --partition slice:1/4   # Job 1 of 4
testx --partition slice:2/4   # Job 2 of 4

# Hash-based (stable across test additions)
testx --partition hash:1/3

GitHub Actions example:

jobs:
  test:
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - run: testx --partition slice:${{ matrix.shard }}/4

Flaky test detection

# Run tests 10 times (default)
testx stress

# Run 50 iterations, stop on first failure
testx stress -n 50 --fail-fast

# Cap total time at 60 seconds
testx stress --max-duration 60

Output:

Stress Test Report: 10/10 iterations in 5.23s

  Flaky Tests Detected:
    test_network_call (7/10 passed, 70.0% pass rate, avg 12ms)

Impact analysis

Only run tests when relevant source files changed:

# Skip tests if only docs changed
testx --affected

# Analyze what changed without running
testx impact

# Compare against a branch
testx impact --mode branch:main

Smart caching

# Skip re-running if source files haven't changed
testx --cache

# Clear the cache
testx cache-clear

Monorepo / workspace

Scan a monorepo and run tests across all detected projects:

# Discover and test all projects
testx workspace

# List projects without running
testx workspace --list

# Only test Rust and Python projects
testx workspace --filter rust,python

# Include directories normally skipped (e.g., packages/)
testx workspace --include packages

# Run sequentially instead of in parallel
testx workspace --sequential

Test history & analytics

Track test health over time:

# Quick overview
testx history

# Flaky test report
testx history flaky

# Slowest tests trend
testx history slow

# Health score dashboard (A–F grading)
testx history health

# Last 50 runs
testx history runs --last 50

Interactive test picker

testx pick

Fuzzy-search through all discovered tests, select one or more, and run only those.

Other options

testx --slowest 5        # Show 5 slowest tests
testx --timeout 60       # Kill tests after 60 seconds
testx --raw              # Show raw runner output
testx -v                 # Verbose (show detected command)
testx -w                 # Watch mode — re-run on file changes
testx --retries 3        # Retry failed tests 3 times
testx --reporter github  # Activate GitHub Actions reporter

Configuration

Create a testx.toml in your project root (or run testx init):

# Override detected adapter
# adapter = "python"

# Extra arguments for the test runner
args = ["-v", "--no-header"]

# Timeout in seconds (0 = no timeout)
timeout = 60

# Environment variables
[env]
CI = "true"

CLI flags always override config file values.

Plugin System

Custom adapters

Define custom test commands in testx.toml:

[[adapters]]
name = "my-framework"
detect = ["my-config.json"]
command = "my-test-runner"
args = ["--reporter", "json"]
output_format = "json"

Reporter plugins

Built-in reporters:

• Markdown — Generate markdown test reports
• GitHub Actions — Annotations with ::error:: / ::warning::
• HTML — Standalone HTML report
• Desktop notifications — System notification on completion

Building from Source

git clone https://github.com/whoisdinanath/testx.git
cd testx
cargo build --release

Running the test suite

cargo test            # Run all tests (1134 tests)
cargo clippy          # Lint (0 warnings)
cargo fmt --check     # Format check

Stats

Documentation

Full documentation is available at testx-cli.readthedocs.io.

• Getting Started
• Configuration Guide
• Output Formats
• CI Sharding
• Plugin System
• CLI Reference

Contributing

We welcome contributions! Please read these before getting started:

• Contributing Guide — Setup, workflow, and PR process
• Coding Guidelines — Architecture, code style, and module design
• Bug Report Template — Report a bug
• Feature Request Template — Suggest a feature

Pull requests are reviewed against the PR template checklist.

License

MIT