Backtesting Engine Loop Design

Quick definition: the engine loop is the causality contract that decides what data the strategy can see, when a signal exists, when an order can be filled, and how the exit is resolved.

The engine loop is where a backtest either becomes a replay or becomes a story about the future. A useful loop walks the market forward, loads only the state available at each decision, records skips, and refuses to fill trades that cannot be supported by the configured market data.

Why this matters

Most attractive backtest bugs are timing bugs. A completed bar creates a signal, but the simulator fills at a price that existed before the signal. A stop is marked hit before the option quote used to prove it. A daily filter uses the current session close. These are small implementation details, but they change the scientific meaning of the result.

The engine loop should make those errors hard to express. It should separate setup detection, entry timing, contract selection, execution, exit resolution, and logging.

Daily replay shape

For intraday options strategies, a clear loop usually looks like this:

bash

for day in trading_days:
    session = load_underlying_session(ticker, day)
    daily_context = load_daily_context(ticker, day)
    option_context = load_contract_context(ticker, day)

    setup = strategy.find_setup(session, daily_context)
    if setup is None:
        record_skip(day, "no_setup")
        continue

    exit_plan = strategy.resolve_exit(session, setup)
    trade = option_engine.try_express_setup(
        ticker=ticker,
        day=day,
        setup=setup,
        exit_plan=exit_plan,
        option_context=option_context,
    )
    record_trade_or_rejection(trade)

The exact implementation can be more complex, but the direction should stay the same: load the causal state, find a setup, choose an instrument, simulate execution, then log the result.

Signal time and entry time

The most important rule is that a completed bar can create a signal, but it cannot also give the strategy an intrabar fill before the signal existed. If a signal is generated on bar t, the conservative default is entry on the next observable bar or quote after t.

For example, an opening-range breakout can:

Build the opening range from completed bars.
Detect a breakout after the range is known.
Set signal_ts to the completed signal bar.
Set entry_ts to the next bar open or the next quote that passes the execution policy.

This rule is not cosmetic. Same-bar entry is one of the easiest ways to overstate a momentum strategy. If a framework intentionally supports standing orders, that state should be explicit before the bar completes.

Engine boundaries

Keep these records separate in the code:

Record	Should contain	Should not contain
Config	Strategy parameters, option filters, risk limits, and fill rules.	Results from the current run.
Session state	Underlying bars and context available for the day.	Future bars or final day summary.
Setup	Direction, signal timestamp, entry timestamp, underlying entry price, and feature metadata.	Contract-specific fill assumptions.
Exit plan	Exit timestamp, stop/target result, and reason.	Final option exit price before quote validation.
Option attempt	Selected or rejected contract, structure, quote evidence, and rejection counters.	Strategy feature computation.
Trade	Final quantity, entry price, exit price, PnL, return, and audit metadata.	Hidden fallback decisions.

When a skip happens, log it. No-trade days are part of the result set because they explain coverage, density, and feasibility.

Implementation checklist

Step	Required behavior	Reject or skip reason
Load bars	Verify session coverage before signal generation.	`missing_underlying_bars`
Build setup	Use completed bars and predeclared context only.	`no_setup`
Resolve entry	Enter after signal time, not before it.	`entry_after_cutoff`
Discover contracts	Use point-in-time contracts and DTE filters.	`no_contracts_in_dte_window`
Validate quote	Check bid, ask, spread, size, and quote age.	`quote_missing_near_entry`
Resolve exit	Price target, stop, or time exit with observable data.	`exit_quote_missing`
Log result	Preserve fill source, timestamps, and rejects.	`artifact_write_failed`

Strategy families

The public cutebacktests runtime can support different signal families as long as they share the same replay contract:

opening-range breakout and continuation
VWAP and z-score mean reversion
relative-strength or proxy-relative logic
daily forecast profiles expressed through options

The strategy family changes the setup. It should not change the framework's causal discipline. If one family needs a special entry rule, make that rule visible in the profile and test it directly.

Failure modes to test

Engine tests should cover no bars for a day, setup exists but no eligible contract exists, contract exists but no quote window exists near entry, signal timestamp after allowed entry cutoff, entry timestamp at or after exit timestamp, exit target observable only after the relevant timestamp, and multiple symbols trading on the same calendar day.

The test names should read like a checklist for future developers. A failing test should tell them whether the engine leaked time, selected the wrong universe, filled without evidence, or computed the wrong portfolio unit.

Backtesting Framework

Docs