DEXBot2 Test Suite

Tests live as standalone .ts files in this directory. They are compiled to dist/tests/ by the build and run from there with plain node — no test framework, no TypeScript loader. The suite uses Node's native assert.

Quick Start

# Run all tests (builds production code + tests first)
npm test

# Run a single test file
npm run build:tests
node dist/tests/<file>.js

# Run the archived legacy suites (excluded from `npm test`)
npm run test:legacy

Directory Layout

tests/
  helpers/          # Shared test infrastructure (stubs, mocks, utilities)
  tmp/              # Scratch space for tests that write temp files
  tsconfig.json     # Test-specific TS config (extends root)
  <name>.ts         # Test files (one file per module or concern)

helpers/ contains reusable test support:

• bitshares_client_stub.ts — mock blockchain client
• bitshares_native_stub.ts — mock native chain client
• chain_keys_stub.ts — key derivation test doubles
• chain_orders_stub.ts — order lifecycle test doubles
• fee_cache_init.ts — fee cache seeding for tests
• order_test_helpers.ts — order construction utilities
• silent_logger.ts — suppresses log output during tests
• module_cache_stub.ts — isolates module state per test
• unlock_test_helpers.ts, foreign_cred_stub.js, dynamic_weight_files.ts — domain-specific helpers

Test Categories

Tests are organized by concern, not by directory — patterns like test_<area>*.ts indicate the focus area. Below is a thematic guide with representative files (run ls tests/*.ts for the full list).

Core Infrastructure

Connection, subscriptions, node management, native chain client. Examples: test_subscriptions.ts, test_node_manager.ts, test_native_chain_client.ts, connection_test.ts

Account & Authentication

Key validation, balance queries, account selection. Examples: test_key_validation.ts, test_account_totals.ts, test_account_selection.ts, test_chain_keys_vault.ts

Market Data & Pricing

Price derivation, orderbook inspection, tolerance checks. Examples: test_market_price.ts, test_price_derive.ts, test_price_tolerance.ts, test_any_pair.ts, test_kibana_candles.ts, test_fetch_book_data.ts, test_window_cache.ts

Market Adapter

AMA signal processing, price offset, bound clamping, signal gates. Examples: test_market_adapter_logic.ts, test_market_adapter_service.ts, test_market_adapter_signal_gates.ts, test_market_adapter_integration_core.ts

Analysis & Charting

Research/analysis tools: chart generators, backtests, and the grid-reset replay used by the TradingView exporter (GRID_RECALCULATION.md). Examples: test_grid_reset_sim.ts, test_tradingview_chart_storage_key.ts, test_backtest_bot_fitting_logic.ts

Order Management & Execution

Order lifecycle, fill processing, trade history, batch execution. Examples: test_open_orders.ts, test_fills.ts, test_fill_batch_chunking.ts, test_fill_replay_guards.ts, test_uncertain_broadcast.ts

Strategy & Grid Logic

Grid generation, sizing, rotation, divergence detection, reconciliation. Examples: test_order_grid.ts, test_strategy_logic.ts, test_grid_reconcile.ts, test_working_grid.ts, test_rotation_order_sizing.ts, test_strategy_edge_cases.ts, test_reserve_orders.ts

Copy-on-Write (COW) Rebalancing

Concurrent-safe rebalancing with isolated working grids — dedicated test suite. Examples: test_cow_master_plan.ts, test_cow_concurrent_fills.ts, test_cow_commit_guards.ts, test_cow_divergence_correction.ts, test_cow_static_analysis.ts

Fees & Accounting

Fee deduction, fund tracking, precision, invariant checks. Examples: test_accounting_logic.ts, test_fee_cache.ts, test_bts_fee_accounting.ts, test_core_fee_accounting.ts, test_funds.ts, test_precision_quantization.ts

Integration & Workflows

Cross-module scenarios: startup reconciliation, engine integration, market simulations. Examples: test_engine_integration.ts, test_market_scenarios.ts, test_grid_reconcile.ts (GRID_RECONCILE.md), test_startup_decision.ts, test_main_loop_sync_fill_rebalance.ts

Credential Daemon & Runtime

Credential management, daemon lifecycle, session caching, debt policy. Examples: test_credential_daemon.ts, test_credential_runtime.ts, test_credential_session_cache.ts, test_credit_runtime.ts

PM2 & Process Management

PM2 lifecycle, startup ordering, bot supervision, launcher version reporting. Examples: test_pm2_logic.ts, test_pm2_main_output.ts, test_bot_supervisor.ts, test_unlock_main.ts, test_version_notice.ts

Diagnostics & Benchmarks

Interactive tools and performance benchmarks (not part of CI). Examples: connection_test.ts, diag_adapter_client.ts, diag_ws_nodes.ts, diag_ws_lifecycle.ts, benchmark_cow.ts, sim_batching.ts, repro_phantom_orders.ts

Edge Cases & Regression

Tests targeting specific bugs, race conditions, and failure modes. Examples: test_critical_bug_fixes.ts, test_race_condition_fixes_batch1.ts, test_patch17_invariants.ts, test_shutdown_reentrancy.ts, test_multifill_opposite_partial.ts, test_correction_queue_staleness.ts, test_spread_pure_fund_driven.ts, test_sync_lock_id_verification.ts

Utilities & Helpers

Shared utility functions, precision handling, chain helpers. Examples: test_utils.ts, test_chain_helpers.ts, test_precision_integration.ts, test_fund_cycling_trigger.ts, test_manager.ts

Key Architectural Patterns Tested

Copy-on-Write (COW) Rebalancing

• Master grid remains immutable during rebalancing
• Working grids are isolated copies for planning
• Fills arriving mid-rebalance are synchronized
• Delta building identifies changes between grids
• Atomic commits apply changes only on success

Reference: docs/COPY_ON_WRITE_MASTER_PLAN.md

RMS Divergence Checking

• Quadratic penalty for large errors
• Concentrated errors raise RMS threshold
• Grid recalculation triggers at correct levels

Fund Invariants

• Available funds never exceed free blockchain balance
• Committed funds tracked across state transitions
• Fee deductions and refunds maintain consistency
• No double-spending between orders

Reference: docs/FUND_MOVEMENT_AND_ACCOUNTING.md

Grid-Price Invariant & Hold Guards

• Every emitted order's price must equal its slot's genesis level (priceForSlot(idx, genesis)); off-grid emissions are blocked, not counted
• The guard itself plus the live batch wiring, escalation thresholds, and per-order stranded-hold clocks are each pinned and mutation-tested
• Adoption keeps the slot's own level; loadGrid repairs a pre-existing off-grid slot price
• A snapshot with no usable ladder is refused at load (MISSING_GENESIS_POLICY rebuild/halt) and the sync entry refuses rather than falling back to a tolerance matcher

Reference: docs/GRID_PRICE_INVARIANT.md

Examples: test_grid_price_invariant_guard.ts, test_grid_price_invariant_wiring.ts, test_grid_price_slot_invariant.ts, test_final_pivot_gate.ts, test_hold_and_center_guards.ts, test_sync_out_of_grid_defer.ts, test_missing_genesis_policy.ts, test_last_fill_pivot_persistence.ts

Documentation References

• Documentation Index: docs/README.md
• Module Architecture: modules/README.md
• Copy-on-Write: COPY_ON_WRITE_MASTER_PLAN.md
• Fund Accounting: FUND_MOVEMENT_AND_ACCOUNTING.md
• Logging: LOGGING.md
• Developer Guide: developer_guide.md

Note: Interactive/diagnostic scripts (connection_test.ts, diag_*) require network access and are not part of CI. Run these manually when debugging.