BullTrackers Calculation Engine Test Suite

This document provides a comprehensive overview of the automated test suite for the BullTrackers calculation engine. The primary purpose of this suite is to validate the correctness, performance, and data integrity of every calculation node in the system.

1. High-Level Design

The test suite is built around a "single-pass" architecture. It runs every calculation, from the simplest to the most complex, in an order determined by their dependencies. The output of one calculation can be used as the input for subsequent ones, simulating the real-world production environment.

The core philosophy is deep introspection. Instead of just checking the final output, we use a powerful instrumentation layer to monitor every step of a calculation's execution.

2. Core Components

The suite is composed of several key modules that work together:

| File | | :--- | Role | Description | | test-all-calculations.js | Master Test Runner | The main entry point. It invokes the suite, runs all calculations, and generates a final SUMMARY.json report. | | src/run-calculation-suite.js | Suite Orchestrator | Manages the execution of a group of calculations, respecting their dependency graph. | | src/worker.js | Single Test Executor | The heart of a single test. It prepares mock data, instruments the calculation, runs it, and saves the detailed output reports. | | src/harness.js | Instrumentation Layer | Provides the QuantumMonitor proxy that wraps a calculation instance to record its every move. | | src/data-generator.js | Mock Data Generator | Creates realistic, coherent mock data based on financial models (e.g., Geometric Brownian Motion). |

3. The "Quantum Monitor" Test Harness

The QuantumMonitor (defined in harness.js) is the advanced instrumentation layer that provides deep insight into a calculation's behavior. It does not use traditional mocking or stubbing. Instead, it uses a JavaScript Proxy to create a transparent wrapper around a calculation class instance.

3.1. How the Proxy Works

When a test worker runs a calculation, it doesn't use the raw class. It uses the proxied version. This proxy intercepts all interactions with the instance, allowing the monitor to record:

• Function Calls: Every time a method (like process() or an internal helper) is called.
• Arguments & Return Values: The exact data passed into and returned from every function.
• Execution Time: High-resolution timing for every single method call.
• Property Access: Records get and set operations on the instance's properties.
• Errors: Captures any exceptions thrown during execution.
• Memory Usage: Takes periodic snapshots of the V8 heap to track memory consumption.
• Data Flow: Traces how data is transformed, from the initial process() call to the final getResult().

3.2. Generated Reports

For each calculation, the worker generates a dedicated folder in Backend/Core/calculations/test_reports/. This folder contains:

• computation_result.json: The raw JSON output of the getResult() method.
• report.json: A detailed summary of the execution, including performance stats, function call counts, and validation status.
• timeline.html: An interactive HTML report showing a chronological event log of the entire execution.
• dataflow.svg: A visual graph that shows the dependencies and data flow between the calculation and its inputs.

4. The Math Layer (math_primitives.js)

To ensure consistency and prevent logic duplication, all calculations are forbidden from accessing raw portfolio data directly. Instead, they must use the math_primitives.js layer. This layer is injected into the context of every calculation during the test run.

It serves as a single source of truth for data access and common financial calculations.

Key Abstractions:

• SCHEMAS: A constant object defining the core data model types, primarily USER_TYPES.NORMAL and USER_TYPES.SPECULATOR.
• DataExtractor: A static class that provides a unified API to access data from the two different portfolio schemas. For example, DataExtractor.getPositions(portfolio, userType) correctly returns AggregatedPositions for a Normal user and PublicPositions for a Speculator. It abstracts away the underlying structural differences.
• HistoryExtractor: Provides standardized functions for accessing data from a user's trade history document (e.g., getTradedAssets, getSummary).
• SignalPrimitives: Contains functions for more advanced mathematical operations used in signal processing, such as normalizeTanh (Hyperbolic Tangent Normalization) and normalizeZScore.
• MathPrimitives: Provides basic statistical functions like average, median, and standardDeviation.
• Aggregators: Contains helper functions for bucketing and grouping data, such as bucketUsersByPnlPerAsset.

5. Data Schemas

The entire system relies on a set of well-defined data schemas for inputs (portfolios, history) and outputs (calculation results).

5.1. Input Schemas

These schemas are generated by the data-generator.js to simulate real-world user data.

A. Normal User Portfolio (USER_TYPES.NORMAL)

Represents a typical, long-term investor. Positions are grouped by asset.

{
  "UserID": 12345,
  "AggregatedPositions": [
    {
      "InstrumentID": 200010,
      "Invested": 25.5,    // % of total capital initially allocated
      "NetProfit": 12.5,   // % gain/loss on this asset
      "Value": 28.68       // Current value as % of total portfolio equity
    }
  ],
  "AggregatedPositionsByInstrumentTypeID": [ /* ... */ ]
}

B. Speculator User Portfolio (USER_TYPES.SPECULATOR)

Represents an active trader with individual, leveraged positions.

{
  "UserID": 67890,
  "Invested": 5000.00,
  "NetProfit": 2.41,
  "PublicPositions": [
    {
      "PositionID": "987654321",
      "InstrumentID": 200020,
      "Direction": "Buy",
      "CurrentRate": 1300.0,
      "OpenRate": 1250.0,
      "Leverage": 5,
      "NetProfit": 4.0,
      "StopLossRate": 1200.0,
      "TakeProfitRate": 1400.0
    }
  ]
}

C. Trade History

Represents a user's historical trading performance.

{
  "UserID": 1000001,
  "all": {
    "totalTrades": 150,
    "winRatio": 65.0,
    "avgLossPct": -25.5,
    "avgProfitPct": 45.0
  },
  "assets": [ /* breakdown by instrument */ ]
}

6. How to Run the Tests

The entire test suite can be executed with a single command from the /Backend/Entrypoints/BullTrackers/Backend/tests directory.

node test-all-calculations.js

This command will:

1. Discover all calculation files.
2. Determine the correct execution order.
3. Run every calculation through the instrumented test worker.
4. Generate the detailed reports for each one.
5. Create a final SUMMARY.json in the test_reports directory with a high-level overview of passes, failures, and warnings.

Reports are saved to: c:\Users\aiden\Desktop\code_projects\Bulltrackers2025\Backend\Entrypoints\BullTrackers\Backend\Core\calculations\test_reports