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

> Easily run Rust and Python tests for Nautilus Trader using simple make commands. Ensure your codebase is robust by executing `make cargo-test` and `make pytest` after dependency installation.

- Repository: [Nautech Systems/nautilus_trader](https://github.com/nautechsystems/nautilus_trader)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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.

```bash

# Install all Python dependencies and Rust crates

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

```

This command reads [`pyproject.toml`](https://github.com/nautechsystems/nautilus_trader/blob/main/pyproject.toml) and `uv.lock` to install Python packages, while [`Cargo.toml`](https://github.com/nautechsystems/nautilus_trader/blob/main/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`):

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

```bash
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):

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

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

```bash
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`](https://github.com/nautechsystems/nautilus_trader/blob/main/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:

```bash

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

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