How to Run the Rust and Python Test Suites for Nautilus Trader

Run make cargo-test for Rust tests and make pytest for Python tests after installing dependencies with uv sync --all-groups --all-extras.

Nautilus Trader is a high-performance algorithmic trading platform built with a Rust core engine and Python bindings. The repository provides a unified Makefile that orchestrates both test suites, handling feature flags, parallel execution, and environment configuration automatically.

Prerequisites and Environment Setup

Before running any tests, install the unified development environment. Nautilus Trader uses uv for Python dependency management and cargo for Rust compilation.

# Install all Python dependencies and Rust crates

uv sync --all-groups --all-extras

This command reads pyproject.toml and uv.lock to install Python packages, while Cargo.toml defines the Rust workspace members and feature flags.

Running the Rust Test Suite

The Rust test suite uses cargo-nextest as the test runner for parallel execution and detailed failure reporting. The Makefile defines three primary targets for different testing scopes.

Full Rust Test Suite (cargo-test)

Run all Rust crates with the default feature set (ffi,python,high-precision,defi):

make cargo-test

This target executes cargo nextest run --workspace --features "$(CARGO_FEATURES)" with RUST_BACKTRACE=1 exported for detailed panic output. By default, it shows only failures and flaky tests; set VERBOSE=true for full output.

Core-Only Tests (cargo-test-core)

For faster iteration on the engine internals, run only the core crates excluding adapters and CLI tools:

make cargo-test-core

This target iterates over CORE_CRATES (defined in the Makefile) and passes each crate to cargo nextest run with the -p flag, significantly reducing compilation time when working on the trading engine logic.

Extended Tests with Optional Features (cargo-test-extras)

Run the full suite with optional features enabled (capnp for Cap'n Proto serialization and hypersync for Ethereum data ingestion):

make cargo-test-extras

This is a convenience shortcut that invokes cargo-test with EXTRA_FEATURES="capnp,hypersync", useful for integration testing with external data sources.

Understanding Rust Test Configuration

The Makefile controls test behavior through environment variables:

• VERBOSE=true – Shows all test output instead of just failures
• FAIL_FAST=true – Stops on first failure (removes --no-fail-fast)
• EXTRA_FEATURES="feature1 feature2" – Appends features to the default set
• HYPERSYNC=true – Convenience flag to enable the hypersync feature

Running the Python Test Suite

The Python test suite uses pytest with parallel execution via pytest-xdist. Tests cover the Python bindings (PyO3) and high-level trading components.

Standard Unit Tests (pytest)

Run all Python unit tests with optimal parallelization:

make pytest

This executes uv run --active --no-sync pytest with the following configuration:

• -n logical – Uses all logical CPU cores
• --dist=loadgroup – Balances test load across workers
• --new-first and --failed-first – Prioritizes recent and previously failing tests
• --tb=line – Shows concise tracebacks
• --maxfail=50 – Stops after 50 failures

Performance Benchmarks (test-performance)

Execute the performance test suite using codspeed for benchmarking:

make test-performance

This runs pytest tests/performance_tests with --benchmark-disable-gc to prevent garbage collection interference and --codspeed for accurate performance regression detection.

Python Test Configuration Details

The Python test environment is defined in pyproject.toml and locked in uv.lock. The Makefile uses uv run --active --no-sync to ensure the test runner uses the exact dependency versions specified in the lockfile without re-syncing.

Complete Testing Workflow

For a full CI-style validation of both codebases:

# Install all dependencies

uv sync --all-groups --all-extras

# Run Rust tests with all optional features

make cargo-test-extras

# Run Python unit tests

make pytest

For rapid development iteration on core Rust logic:

make cargo-test-core VERBOSE=true

Summary

• Use make cargo-test to run the complete Rust test suite with cargo nextest, supporting features like ffi, python, high-precision, and defi.
• Use make cargo-test-core for faster feedback when working only on core engine crates, excluding adapters and CLI components.
• Use make cargo-test-extras to include optional capnp and hypersync features in Rust testing.
• Use make pytest to execute the Python test suite with parallel workers (-n logical) and intelligent test ordering.
• Use make test-performance to run benchmarks under codspeed for performance regression detection.
• Control test behavior with environment variables: VERBOSE=true, FAIL_FAST=true, EXTRA_FEATURES, and HYPERSYNC=true.

Frequently Asked Questions

What is the difference between cargo-test and cargo-test-core?

cargo-test runs the entire Rust workspace including adapters, CLI tools, and optional components, while cargo-test-core limits execution to the core trading engine crates (nautilus-trading, nautilus-core, etc.). Use cargo-test-core for faster iteration when you are not modifying adapter code.

How do I enable the hypersync feature when running Rust tests?

Set the HYPERSYNC=true environment variable or use the cargo-test-extras target. For example: make cargo-test HYPERSYNC=true or make cargo-test-extras. This enables the Ethereum hypersync data ingestion features during testing.

Why does the Python test suite use uv run instead of direct pytest?

The uv run --active --no-sync command ensures that pytest executes within the exact Python environment defined by uv.lock, without triggering a re-sync of dependencies. This guarantees reproducible test runs across different machines and CI environments while avoiding the overhead of pip install steps.

Can I run both Rust and Python tests with a single command?

While there is no single make target that runs both suites sequentially, you can chain them: make cargo-test && make pytest. For CI pipelines, the repository uses separate workflow steps for Rust and Python tests to maintain clear separation of concerns and parallelization opportunities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}