binary-options-tools-core-pre 0.2.0

Low-level WebSocket client and protocol handler for binary options trading. Core foundation providing connection management, message routing, and async communication primitives.
Documentation

Binary Options Tools - Core Pre - Testing Framework

A comprehensive WebSocket testing and monitoring framework for the binary-options-tools-core-pre crate.

Overview

This framework provides advanced statistics tracking, connection monitoring, and testing capabilities for WebSocket-based applications. It wraps around the existing Client and ClientRunner architecture to provide detailed insights into connection performance and reliability.

Quick Start

1. Basic Usage

use binary_options_tools_core_pre::testing::{TestingWrapper, TestingWrapperBuilder};
use binary_options_tools_core_pre::builder::ClientBuilder;
use std::time::Duration;

// Create your client and runner as usual
let (client, runner) = ClientBuilder::new(connector, state)
    .with_module::<YourModule>()
    .build()
    .await?;

// Wrap with testing capabilities
let mut testing_wrapper = TestingWrapperBuilder::new()
    .with_stats_interval(Duration::from_secs(30))
    .with_log_stats(true)
    .with_connection_timeout(Duration::from_secs(10))
    .build(client, runner);

// Start the wrapper (this will run the ClientRunner and begin collecting statistics)
testing_wrapper.start().await?;

// Use the client through the wrapper
let client = testing_wrapper.client();
// ... use client as normal ...

// Get statistics
let stats = testing_wrapper.get_stats().await;
println!("Connection success rate: {:.1}%",
    stats.successful_connections as f64 / stats.connection_attempts as f64 * 100.0);

// Stop the wrapper (graceful shutdown)
testing_wrapper.stop_and_shutdown().await?;

2. Run the Example

cargo run --example testing_echo_client

3. Run Tests

cargo test testing_wrapper

Features

✅ Currently Implemented

  • Connection Statistics: Track attempts, successes, failures, disconnections
  • Performance Metrics: Latency, uptime, throughput measurements
  • Message Tracking: Count and data volume of sent/received messages
  • Event History: Detailed log of connection events with timestamps
  • Statistics Export: JSON and CSV export formats
  • Real-time Monitoring: Configurable periodic statistics logging
  • Testing Configuration: Flexible configuration for different testing scenarios

Statistics Collected

  • Connection attempts, successes, failures, disconnections
  • Average and last connection latency
  • Total and current connection uptime
  • Time since last disconnection
  • Message counts and data volumes
  • Throughput rates (messages/second, bytes/second)
  • Connection success rate
  • Event history with timestamps

Configuration Options

  • Stats Interval: How often to collect and log statistics
  • Log Stats: Whether to log statistics to console
  • Track Events: Whether to track detailed connection events
  • Max Reconnect Attempts: Maximum number of reconnection attempts
  • Reconnect Delay: Delay between reconnection attempts
  • Connection Timeout: Connection timeout duration
  • Auto Reconnect: Whether to automatically reconnect on disconnection

API Reference

TestingWrapper

The main wrapper class that provides testing capabilities:

pub struct TestingWrapper<S: AppState> {
    // Internal fields
}

impl<S: AppState> TestingWrapper<S> {
    pub async fn start(&mut self) -> CoreResult<()>
    pub async fn stop(&mut self) -> CoreResult<()>
    pub async fn stop_and_shutdown(self) -> CoreResult<()>
    pub async fn get_stats(&self) -> ConnectionStats
    pub async fn export_stats_json(&self) -> CoreResult<String>
    pub async fn export_stats_csv(&self) -> CoreResult<String>
    pub fn client(&self) -> &Client<S>
    pub fn client_mut(&mut self) -> &mut Client<S>
}

TestingWrapperBuilder

Builder pattern for creating testing wrappers:

pub struct TestingWrapperBuilder<S: AppState> {
    // Internal fields
}

impl<S: AppState> TestingWrapperBuilder<S> {
    pub fn new() -> Self
    pub fn with_stats_interval(self, interval: Duration) -> Self
    pub fn with_log_stats(self, log_stats: bool) -> Self
    pub fn with_track_events(self, track_events: bool) -> Self
    pub fn with_max_reconnect_attempts(self, max_attempts: Option<u32>) -> Self
    pub fn with_reconnect_delay(self, delay: Duration) -> Self
    pub fn with_connection_timeout(self, timeout: Duration) -> Self
    pub fn with_auto_reconnect(self, auto_reconnect: bool) -> Self
    pub fn build(self, client: Client<S>, runner: ClientRunner<S>) -> TestingWrapper<S>
}

ConnectionStats

Statistics structure with comprehensive metrics:

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConnectionStats {
    pub connection_attempts: u64,
    pub successful_connections: u64,
    pub failed_connections: u64,
    pub disconnections: u64,
    pub reconnections: u64,
    pub avg_connection_latency_ms: f64,
    pub last_connection_latency_ms: f64,
    pub total_uptime_seconds: f64,
    pub current_uptime_seconds: f64,
    pub time_since_last_disconnection_seconds: f64,
    pub messages_sent: u64,
    pub messages_received: u64,
    pub bytes_sent: u64,
    pub bytes_received: u64,
    pub avg_messages_sent_per_second: f64,
    pub avg_messages_received_per_second: f64,
    pub avg_bytes_sent_per_second: f64,
    pub avg_bytes_received_per_second: f64,
    pub is_connected: bool,
    pub connection_history: Vec<ConnectionEvent>,
}

Advanced Usage

Creating a Custom Testing Platform

pub struct TestingEchoPlatform {
    testing_wrapper: TestingWrapper<()>,
}

impl TestingEchoPlatform {
    pub async fn new(url: String) -> CoreResult<Self> {
        let connector = DummyConnector::new(url);
        let (client, runner) = ClientBuilder::new(connector, ())
            .with_module::<EchoModule>()
            .build()
            .await?;

        let testing_wrapper = TestingWrapperBuilder::new()
            .with_stats_interval(Duration::from_secs(10))
            .with_log_stats(true)
            .with_max_reconnect_attempts(Some(3))
            .build(client, runner);

        Ok(Self { testing_wrapper })
    }

    pub async fn run_performance_test(&self, num_messages: usize, delay_ms: u64) -> CoreResult<()> {
        for i in 0..num_messages {
            let msg = format!("Test message {}", i);
            let response = self.echo(msg).await?;

            if delay_ms > 0 {
                tokio::time::sleep(Duration::from_millis(delay_ms)).await;
            }
        }

        let stats = self.get_stats().await;
        println!("Test completed. Messages sent: {}, received: {}",
            stats.messages_sent, stats.messages_received);

        Ok(())
    }
}

Exporting Statistics

// Export to JSON
let json_stats = testing_wrapper.export_stats_json().await?;
println!("JSON Stats:\n{}", json_stats);

// Export to CSV
let csv_stats = testing_wrapper.export_stats_csv().await?;
println!("CSV Stats:\n{}", csv_stats);

Examples

  • docs/examples/testing_echo_client.rs - Complete example with performance testing
  • tests/testing_wrapper_tests.rs - Unit tests demonstrating usage

Future Enhancements

See docs/testing-framework.md for planned features including:

  • Scheduled function calls
  • Advanced monitoring capabilities
  • Performance benchmarking
  • Enhanced kanal integration
  • Reporting and visualization
  • Configuration management

Contributing

When adding new features:

  1. Update the statistics structures if new metrics are needed
  2. Add appropriate tracking in the StatisticsTracker
  3. Update the documentation
  4. Add examples demonstrating new features
  5. Consider backward compatibility

License

This framework is part of the binary-options-tools-core-pre crate and follows the same license.