Wickra Strategy-CI

Jest for trading strategies. Golden-pin your strategy's backtest report, catch regressions in CI, and property-test it against fuzzed market data — in ten languages, plus a reusable composite GitHub Action.

Part of the Wickra ecosystem. Strategy-CI is the test harness for the deterministic wickra-backtest engine: it runs a strategy through the engine, pins the resulting BacktestReport, and fails the build when the numbers drift.

# Run a directory of strategy tests against a directory of OHLCV data.
# Exits non-zero the moment a report drifts, so CI fails on it.
wickra-strategy-ci run tests/ --data data/

# Re-pin the goldens after a change you meant to make.
wickra-strategy-ci bless tests/ --data data/

Why

A backtest is only trustworthy if it is reproducible. Wickra's engine is deterministic, so a strategy's report is a stable artifact you can pin — like a snapshot test. Strategy-CI turns that into a workflow:

• Golden tests — pin a strategy's BacktestReport and fail when it changes beyond a tolerance you set — absolute or relative, per field, with exact equality as the default when you set none.
• Property tests — assert invariants that must hold for any run: no field is NaN or infinite, drawdown stays inside a bound, the trade count clears a floor, Sharpe or PnL clears a threshold, a named field stays in range.
• Fuzz tests — perturb the input data with a seeded PRNG and re-run, catching strategies that only work on one specific history.

A test is a file, not a function

There is no test API to learn. A test is JSON: which strategy, over which dataset, pinned to which report, under which tolerances.

{
  "id": "crossover",
  "dataset_ref": "sym-04",            // resolves to <data>/sym-04.csv
  "strategy": { /* opaque StrategySpec, forwarded to wickra-backtest */ },
  "expected": { /* the pinned BacktestReport — written by `bless` */ },
  "tolerances": {
    "*": { "kind": "rel", "value": 0.0001 },        // default for every field
    "metrics.sharpe": { "kind": "abs", "value": 0.01 }
  },
  "property_checks": [
    { "kind": "no_nan" },
    { "kind": "max_drawdown_le", "value": 1.0 }
  ],
  "fuzz": { "seed": 42, "runs": 8,
            "perturbation": { "kind": "jitter", "amount": 0.001 } }
}

Write the strategy, run bless once to pin the report, and commit the file. From then on run fails the build whenever the numbers move further than you allowed. Working examples live in golden/tests/.

wickra-strategy-ci list  tests/                 # the test ids found under a path
wickra-strategy-ci run   tests/ --data data/    # --format json for machine output
wickra-strategy-ci bless tests/ --data data/    # re-pin after an intended change

As a GitHub Action

Run your strategy tests on every push — a failing test fails the workflow:

- uses: wickra-lib/wickra-strategy-ci@v0.1.2
  with:
    tests: tests/
    data: data/

Pin the exact release. Pre-1.0 the moving major tag is @v0, and it floats across minor versions, which may break.

See docs/GITHUB_ACTION.md for the full inputs/outputs.

Use in any language

The core is exposed as a JSON-over-C-ABI data API in ten languages: Rust, Python, Node.js and WASM natively, plus C, C++, C#, Go, Java and R over the C ABI hub. A Session handle plus command(json) -> json and version is the whole surface; the same test JSON produces a byte-identical result in every binding.

cargo add wickra-strategy-ci-core      # Rust
pip install wickra-strategy-ci         # Python
npm install wickra-strategy-ci         # Node.js
dotnet add package Wickra.StrategyCi   # C#
go get github.com/wickra-lib/wickra-strategy-ci/bindings/go   # Go

Java ships to Maven Central (org.wickra:wickra-strategy-ci), R to r-universe (wickrastrategyci), and the C ABI ships as a per-platform library with a vendored header. See each binding's README.md under bindings/.

How it works

A StrategyTest is data, not code: a serde model carrying an opaque StrategySpec sub-JSON. Strategy-CI forwards that spec verbatim to wickra-backtest::run, takes the returned BacktestReport, and asserts it against the test's expectations and properties. Because the engine is deterministic and every binding forwards the core's response string unchanged, results are reproducible byte-for-byte across languages and between the parallel (rayon) and sequential (WASM) execution paths.

The diff works on numeric leaves. Both reports are flattened to a sorted map of numbers — metrics.sharpe, equity[3].equity — rounded to eight decimals and compared field by field, reporting mismatches, fields that vanished and fields that appeared. Strings, booleans and nulls are not pinned, so a report field that is text is outside what a golden can catch.

Benchmarks

A suite is cheap enough to gate every pull request. Median wall-clock for run_suite, parallel path, from the strategy-ci-bench criterion suite:

Per-test cost is dominated by the engine walking the price history — roughly linear in bar count, near-flat in test count once the rayon pool is saturated. The golden diff and property checks are O(fields) on top. A fuzz axis multiplies a test's cost by its runs. Full method and caveats in BENCHMARKS.md; reproduce with cargo bench -p strategy-ci-bench.

Requirements

Building from source additionally needs a Rust toolchain; the polyglot bindings need their own toolchain (maturin, napi, wasm-pack, dotnet, go, Maven, R CMD) only for the binding you are building.

Project layout

crates/wickra-strategy-ci-core     the runner: model, tolerances, properties, fuzz, session
crates/wickra-strategy-ci-cli      the reference CLI (run / bless / list / version)
crates/strategy-ci-bench    criterion benchmarks
bindings/c                  the C ABI hub — every non-native binding goes through it
bindings/python             PyO3 native binding
bindings/node               napi-rs native binding
bindings/wasm               wasm-bindgen binding (sequential path)
bindings/{csharp,go,java,r} thin clients over the C ABI
golden/                     cross-language fixtures: tests, data, expected reports
examples/                   one runnable example per binding
fuzz/                       cargo-fuzz targets (its own detached workspace)
action.yml                  the composite GitHub Action

Building everything from source

cargo build --workspace --all-features        # core, CLI, bench, native bindings
cargo build -p wickra-strategy-ci-c --release # the C ABI library + header

( cd bindings/python && maturin develop --release )
( cd bindings/node   && npm ci && npm run build )
( cd bindings/wasm   && wasm-pack build --target web )
( cd bindings/java   && mvn -q package )
( cd bindings/csharp && dotnet build )

The C ABI library is the prerequisite for the C, C++, C#, Go, Java and R bindings: build it first, then point WKSTRATEGYCI_LIB and WKSTRATEGYCI_INC at the resulting library and bindings/c/include.

Testing

cargo test --workspace --all-features         # core, integration, C ABI
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check

( cd bindings/python && pytest tests -q )
( cd bindings/node   && npm test )
( cd bindings/go     && go test ./... )

Every binding runs the same golden/ fixtures through its own command(json) -> json surface, so a passing suite is evidence that the languages agree byte-for-byte — not just that each one runs. The CLI is covered end-to-end against golden/tests in CI.

Ecosystem

Strategy-CI is one repo in the Wickra family:

Documentation

See docs/ — TESTS.md for the test model, TOLERANCES.md for the golden diff, PROPERTIES.md for the invariants, FUZZING.md for the perturbations, GITHUB_ACTION.md for the action, and Cookbook.md for task-shaped recipes.

Contributing

See CONTRIBUTING.md and the Code of Conduct.

Security

Report vulnerabilities per SECURITY.md.

License

Dual-licensed under either MIT or Apache-2.0, at your option.

Disclaimer

wickra-strategy-ci is research and engineering tooling, not financial advice. A passing test attests only that a strategy's backtest report matches its pinned expectation under the given data — it makes no claim about the quality, profitability or future performance of any strategy. Trading carries risk; you are responsible for your own decisions.