Data Testing Spec

This section defines a rigorous test matrix for validating adapter data functionality using the Rust DataTester actor. Python exposes it as a built-in actor configured through nautilus_trader.testkit.DataTesterConfig; Rust code imports it from nautilus_testkit::testers. Each test case is identified by a prefixed ID (e.g. TC-D01) and grouped by functionality.

Each adapter must pass the subset of tests matching its supported data types.

Test groups are ordered from least derived to most derived data: instruments and raw book data first, then quotes, trades, bars, and derivatives data. An adapter that passes groups 1-4 is considered baseline data compliant.

Document adapter-specific data behavior (custom channels, throttling, snapshot semantics, etc.) in the adapter's own guide, not here.

Prerequisites

Before running data tests:

• Target instrument available and loadable via the instrument provider.
• API credentials set via environment variables ({VENUE}_API_KEY, {VENUE}_API_SECRET) when the venue requires authentication for the data being tested.
• If the venue offers a demo/testnet mode, use credentials created for that environment. Demo and production API keys are typically separate and not interchangeable; using the wrong credentials produces authentication errors (e.g. HTTP 401).

Python node setup:

Use nautilus_trader.live.LiveNode. Call LiveNode.builder(...) when you need to register adapter client factories before the node is built.

from nautilus_trader.common import Environment
from nautilus_trader.config import LiveDataEngineConfig
from nautilus_trader.live import LiveNode
from nautilus_trader.model import TraderId
from nautilus_trader.testkit import DataTesterConfig

node = (
    LiveNode.builder("TESTER-001", TraderId("TESTER-001"), Environment.SANDBOX)
    .with_data_engine_config(LiveDataEngineConfig(time_bars_build_with_no_updates=False))
    .add_data_client(None, adapter_data_client_factory, data_client_config)
    .build()
)

tester_config = DataTesterConfig(
    client_id=client_id,
    instrument_ids=[instrument_id],
    subscribe_quotes=True,
)
node.add_builtin_actor("DataTester", tester_config)
# Register remaining components, then start or run

Rust node setup (reference: crates/adapters/{adapter}/examples/node_data_tester.rs):

use nautilus_testkit::testers::{DataTester, DataTesterConfig};

let tester_config = DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_quotes(true)
    .build()?;
let tester = DataTester::new(tester_config);
node.add_actor(tester)?;
node.run().await?;

Timestamp scale

Nautilus stores ts_event and ts_init as Unix nanoseconds (UnixNanos). Every data message that carries those fields must use that scale, not leftover seconds, milliseconds, or microseconds.

• A value below 10^16 is not a plausible Unix-nanosecond timestamp (10^16 ns is about 116 days after 1970-01-01) and usually means the adapter left the venue scale unconverted.
• Second-precision venue times that were converted correctly end in 000000000 and still pass: that is coarse precision, not a scale error.
• Live stream ts_event should be near wall-clock time for the session. Historical request results may be older and still valid if the scale is nanoseconds.
• ts_init is the local clock when Nautilus created the object. Small ts_event > ts_init skew is possible when the venue clock is ahead.

DataTester warns when ts_event or ts_init fails the scale check on instruments, quotes, trades, bars, book deltas, book depth, mark and index prices, funding rates, instrument status and close, option greeks, and historical batches of those types. It does not check reconstructed books in on_book. Treat a warning as a failure for the case that produced the message.

Order book sync conformance

Adapters that maintain order books from a venue stream must keep their output valid through venue and network faults. Unit and integration suites cannot reproduce venue timing, so changes to book sync and recovery machinery need a deterministic model check and live validation against a real venue. Live validation here means market-data-only observation: subscribe, request, and fault-inject, never place orders. A dark book is a subscribed book that never receives data.

Book stream contract

BookStreamChecker in nautilus_live::book::conformance, enabled by the nautilus-live test-support feature, applies the contract to every emitted OrderBookDeltas batch:

• A batch ends with F_LAST. Each F_LAST closes an event group, and the book must pass its integrity check after every group because consumers observe it at those boundaries.
• A snapshot group is a Clear followed by Add deltas, all flagged F_SNAPSHOT. A lone Clear is an empty snapshot.
• An incremental group carries neither F_SNAPSHOT nor Clear, and follows a snapshot.
• Each incremental group's sequence exceeds the previous one when the venue sequence is monotonic within a snapshot episode. OKX seqId can reset, and Polymarket, Hyperliquid, Betfair, and AX Exchange books carry no venue sequence, so their checkers skip this rule and rely on the oracle.
• A book emits nothing after its unsubscribe settles.

Validation levels

Match the level to the riskiest aspect of the change; higher levels include the bars of every level below.

The L0 property test is schedule_keeps_sync_contract in crates/live/src/book/sync.rs. Record the level, venue, oracle, and result with the change. A fix that live validation finds restarts at the level that found it: the rerun must clear the same bar, not a lighter one.

Fault catalog

Every adapter must produce these outcomes, whichever recovery family it belongs to:

Forcing techniques

Prefer distinct orderings over raw volume: a probe earns its place by forcing an ordering the suite cannot produce (reconnect mid-recovery, a snapshot racing gate-open, an unsubscribe racing an in-flight subscribe), not by message count.

Route each venue through a network location it serves: Polymarket restricts access by region, while OKX, Lighter, Binance, Hyperliquid, and AX Exchange validate direct. Confirm the route delivers venue data before a long run: sockets can connect while the venue stays silent. Branches the venue never produces live belong in a captured-wire deterministic harness, not in the live run.

Oracles

An oracle is an independent reconstruction of venue truth, compared with the emitted book through BookStreamChecker::verify:

• Build it from a separate connection or a REST snapshot, never from the adapter's own state.
• Compare at an aligned venue sequence. Skip a sample that cannot be aligned; it does not count as a pass.
• Count a snapshot episode verified once a comparison after its snapshot succeeds. A harness with Coverage::Episodes, such as OKX, verifies each batch as it arrives and fails a session unless every episode is verified. A harness with Coverage::Samples, such as Binance, matches oracle samples by update ID after the fact, so it reports oracle checks and unmatched samples instead of episode coverage.

Stress harnesses

Stress harnesses are development tools for changes to book sync and recovery code. They are not part of the published crates and do not run in CI. The BookStreamChecker they use ships with nautilus-live under the test-support feature, so other tests can apply the same contract.

An adapter that uses the shared book machinery keeps its live harness at crates/adapters/<venue>/tests/stress/book_stress.rs, registered as a test target named <venue>-book-stress:

[[test]]
name = "okx-book-stress"
path = "tests/stress/book_stress.rs"
harness = false
test = false
required-features = ["examples"]

harness = false lets the target own its runtime and arguments, and test = false keeps it out of default cargo test and nextest runs. Add nautilus-live with the test-support feature to the crate's dev-dependencies.

The shared machinery is test source at crates/live/tests/book/stress/, which each harness compiles in with a path include:

#[path = "../../../../live/tests/book/stress/mod.rs"]
mod stress;

The shared module runs the harness, and the venue supplies only its own pieces by implementing StressVenue:

• A WireCodec that classifies each venue frame as a book snapshot, a book update, or an unsubscribe acknowledgement, recording it in the oracle before any fault applies. It can also rewrite a frame to plant a sequence gap or an in-band mismatch, and answer an adapter subscribe with a venue rejection.
• The proxy routes, the data client configuration, and any extra proxy routes, such as a REST snapshot proxy.
• The oracle comparison for each emitted batch, the condition for a healthy book, and a startup self-check.
• The scenarios, written against Session.

FaultProxy relays the adapter's WebSocket traffic to the venue, or CRLF-delimited lines over raw TCP for a route whose upstream URL is not a WebSocket URL. A line route serves the proxy address alone, and the venue's WireCodec::connect opens its upstream connection, for example over TLS. It applies per-book Fault rules (drop snapshots or updates, corrupt, hold, silence, cut on unsubscribe, reject subscribes) and connection-wide cuts and freezes. Session passes every emitted batch through BookStreamChecker and the oracle, waits for books to heal, and checks at shutdown that every socket and reconnect handle is released.

Every harness accepts the same flags, and venues add their own; --help lists them:

Run the harness explicitly, with adapter environment variables stripped:

CARGO_BUILD_JOBS=16 bash scripts/strip-adapter-env.bash \
  cargo test -p nautilus-okx --features examples --test okx-book-stress -- --timeout 10 --rounds 18

Betfair streams market data only to logged-in accounts, so its harness runs with the Betfair credentials set; see Live recovery validation. AX Exchange market data also requires authentication, so its harness reads sandbox credentials from the environment and runs without the wrapper.

The harness writes one line per event to stderr, each led by a fixed word:

A deadline failure reports the venue frames each proxy route received, which separates a silent route from an adapter failure. A harness = false target cannot run #[test] functions, so the venue proves its wire parsing and oracle in StressVenue::self_check, which runs before any venue traffic. The shared proxy, argument parsing, and wire book carry unit tests in the nautilus-live book test target, run with cargo nextest run -p nautilus-live --features test-support --test book. Document the harness in the adapter's integration guide under a Live recovery validation heading that covers what it checks, the faults it injects, the run command, its scenarios and flags, and the endpoints it requires. OKX, Binance, Lighter, Polymarket, Hyperliquid, Bybit, Betfair, and AX Exchange provide harnesses.

In-band verification

When a venue publishes a book checksum or hash, validate it and treat a mismatch as a gap. It catches corruption in the data it covers that sequence checks miss, without an external oracle. Kraken validates the CRC32 checksum on each L3 update when validate_l3_checksum is enabled, which is the default. Polymarket validates the hash on each book snapshot that carries a hash and its full preimage (see book snapshot validation). OKX books frames carry a zero checksum, so OKX relies on its oracle instead.

Each group below begins with a summary table, followed by detailed test cards. Test IDs use spaced numbering to allow insertion without renumbering.

Group 1: Instruments

Verify instrument loading and subscription before testing market data streams.

TC-D01: Request instruments

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    request_instruments=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .request_instruments(true)
    .build()?

TC-D02: Subscribe instrument

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_instrument=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_instrument(true)
    .build()?

TC-D03: Load specific instrument

Considerations:

• This tests the instrument provider's load / load_async method directly.
• Verify the instrument is cached and available via self.cache.instrument(instrument_id).

Group 2: Order book

Test order book subscription modes and snapshot requests.

Python uses BookType.L2_MBP for these scenarios. The Rust builder can override book_type when an adapter requires a different book representation.

TC-D10: Subscribe book deltas

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_book_deltas=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_book_deltas(true)
    .book_type(BookType::L2_MBP)
    .build()?

TC-D11: Subscribe book at interval

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_book_at_interval=True,
    book_depth=10,
    book_interval_ms=1000,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_book_at_interval(true)
    .book_type(BookType::L2_MBP)
    .book_depth(10)
    .book_interval_ms(1000)
    .build()?

TC-D12: Subscribe book depth

Choose a depth supported by the venue; see the adapter guide for its limit. book_depth applies to all enabled book subscriptions and the book snapshot request. Omitting it uses the adapter default. When depth runs alongside deltas or interval books, DataTester subscribes to depth with managed=False so it cannot overwrite the delta-managed book. When only depth is enabled, its managed setting follows manage_book.

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_book_depth=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_book_depth(true)
    .book_type(BookType::L2_MBP)
    .build()?

TC-D13: Request book snapshot

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    request_book_snapshot=True,
    book_depth=10,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .request_book_snapshot(true)
    .book_depth(10)
    .build()?

TC-D14: Managed book from deltas

Considerations:

• The managed book applies each delta to an OrderBook instance maintained by the actor.
• Use book_levels_to_print to control logging verbosity.

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_book_deltas=True,
    manage_book=True,
    book_levels_to_print=10,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_book_deltas(true)
    .manage_book(true)
    .book_type(BookType::L2_MBP)
    .build()?

DataTesterConfig exposes request_book_deltas, but DataTester does not issue that historical request. Test an adapter's historical book delta support through a custom actor until the tester implements the request path.

Group 3: Quotes

Test quote tick subscriptions and historical requests.

TC-D20: Subscribe quotes

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_quotes=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_quotes(true)
    .build()?

TC-D21: Request historical quotes

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    request_quotes=True,
)

Group 4: Trades

Test trade tick subscriptions and historical requests.

TC-D30: Subscribe trades

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_trades=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_trades(true)
    .build()?

TC-D31: Request historical trades

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    request_trades=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .request_trades(true)
    .build()?

Group 5: Bars

Test bar subscriptions and historical requests.

TC-D40: Subscribe bars

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    bar_types=[BarType.from_str("BTCUSDT-PERP.VENUE-1-MINUTE-LAST-EXTERNAL")],
    subscribe_bars=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .bar_types(vec![bar_type])
    .subscribe_bars(true)
    .build()?

TC-D41: Request historical bars

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    bar_types=[BarType.from_str("BTCUSDT-PERP.VENUE-1-MINUTE-LAST-EXTERNAL")],
    request_bars=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .bar_types(vec![bar_type])
    .request_bars(true)
    .build()?

Group 6: Derivatives data

Test derivatives-specific data streams: mark prices, index prices, and funding rates.

TC-D50: Subscribe mark prices

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_mark_prices=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_mark_prices(true)
    .build()?

TC-D51: Subscribe index prices

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_index_prices=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_index_prices(true)
    .build()?

TC-D52: Subscribe funding rates

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_funding_rates=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_funding_rates(true)
    .build()?

TC-D53: Request historical funding rates

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    request_funding_rates=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .request_funding_rates(true)
    .build()?

Group 7: Instrument status

Test instrument status and close event subscriptions.

TC-D60: Subscribe instrument status

Considerations:

• Status events may only fire on state changes (e.g. trading halt -> resume).
• During normal trading hours, a Trading status may be received on subscribe.

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_instrument_status=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_instrument_status(true)
    .build()?

TC-D61: Subscribe instrument close

Considerations:

• Close events typically fire at end-of-session for traditional markets.
• May not fire for 24/7 crypto venues unless the adapter synthesizes a daily close.

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_instrument_close=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_instrument_close(true)
    .build()?

Group 8: Option greeks

Test option greeks and option chain subscriptions.

TC-D62: Subscribe option greeks

Considerations:

• Greeks are only available for option instruments.
• Values depend on the venue's pricing model and may update on every quote change.
• Some venues (Bybit, Deribit) subscribe per instrument; OKX subscribes per instrument family and filters to the requested instruments.
• rho may be zero when the venue does not provide it (Bybit, OKX).
• underlying_price and open_interest may be None depending on the venue channel.

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_option_greeks=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_option_greeks(true)
    .build()?

TC-D63: Subscribe option chain

Considerations:

• Option chain subscriptions are managed by the DataEngine, which creates per-instrument quote and greeks subscriptions internally.
• Dynamic strike ranges require an ATM price before instrument subscriptions begin. The DataEngine requests an initial reference price and otherwise waits for live option Greeks.
• Not yet configurable via DataTesterConfig; requires manual actor setup with subscribe_option_chain and an OptionSeriesId.

Group 9: Lifecycle

Test actor lifecycle behavior: unsubscribe handling, retirement cleanup, and custom parameters.

TC-D70: Unsubscribe on stop

Python config:

DataTesterConfig(
    instrument_ids=[instrument_id],
    subscribe_quotes=True,
    subscribe_trades=True,
    can_unsubscribe=True,
)

Rust config:

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_quotes(true)
    .subscribe_trades(true)
    .can_unsubscribe(true)
    .build()?

TC-D71: Custom subscribe params

Rust config:

use nautilus_core::Params;
use serde_json::json;

let mut subscribe_params = Params::new();
subscribe_params.insert("key".to_string(), json!("value"));

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .subscribe_quotes(true)
    .subscribe_params(subscribe_params)
    .build()?

Considerations:

• subscribe_params is opaque to the DataTester and passed through to the adapter.
• The Python DataTesterConfig constructor does not expose this Rust-only field.
• Consult the adapter's guide for supported parameters.

TC-D72: Custom request params

Rust config:

use nautilus_core::Params;
use serde_json::json;

let mut request_params = Params::new();
request_params.insert("key".to_string(), json!("value"));

DataTesterConfig::builder()
    .client_id(client_id)
    .instrument_ids(vec![instrument_id])
    .request_quotes(true)
    .request_params(request_params)
    .build()?

Considerations:

• request_params is opaque to the DataTester and passed through to the adapter.
• The Python DataTesterConfig constructor does not expose this Rust-only field.
• Consult the adapter's guide for supported parameters.

TC-D73: Retirement cleanup

The shared bar must remain active after the first actor retires and stop after the final actor retires.

Considerations:

• DataTesterConfig does not cover multi-actor retirement. Create two actors manually, then remove them through Python Controller.remove_actor or Rust Trader::remove_actor.
• If on_dispose fails, the actor must remain registered with its subscriptions intact so a later retirement can release them without invoking the failed hook again.
• A failed on_stop or on_fault must not block retirement: disposal and deregistration must still complete from the corresponding transitional state.

TC-D74: DeFi shared pool demand

Cover these overlaps:

• Two actors with the same subscription type, retired in either order.
• SubscribePool with each narrower type (swaps, liquidity updates, fee collects, flash events), unsubscribed in both orders. The narrower event filters must stay active while either subscription remains.
• The same pool on two data clients. Each client keeps its own demand, and the pool updater stays active until both release.

Considerations:

• DataTesterConfig does not cover DeFi pool subscriptions. Create the actors manually.
• A duplicate unsubscribe from one actor must not release another actor's demand.

TC-D75: DeFi bootstrap cancel

Considerations:

• The second subscription requests a new snapshot only while the pool is absent from the cache. Once the first request's pool definition arrives, a later subscription builds the profiler from the cached pool instead, so the case needs a delayed response.
• An engine reset or disconnect also cancels pending bootstraps. A response that arrives afterwards must not install a profiler.

DataTester configuration reference

The Python constructor accepts the parameters below. Defaults are resolved values after construction. Historical quote, trade, and bar requests use a one-hour lookback; funding rate requests use seven days. The lookback is not configurable through DataTesterConfig.

The Rust builder also exposes these parameters: