simvar 0.3.0

Switchy package
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# MoosicBox Simvar

Simulation variable system and testing harness for deterministic async testing.

## Overview

The MoosicBox Simvar package is a facade that re-exports functionality from:

- **Simvar Harness**: Core simulation testing framework (`simvar_harness`)
- **Simvar Utils**: Simulation utilities (`simvar_utils`, with `utils` feature)
- **Switchy**: Underlying simulation and switching framework

This package provides a unified interface for simulation-based testing with deterministic async execution.

## Core Functionality

The package re-exports from `simvar_harness`:

- **`run_simulation`**: Main function to run simulation tests
- **`SimBootstrap` trait**: Trait for configuring simulation lifecycle hooks (`init`, `on_start`, `on_step`, `on_end`, `props`, `build_sim`)
- **`Sim` trait**: Interface for managing hosts and clients in simulations
- **Configuration types**: `SimConfig`, `SimProperties`, `SimResult`, `SimRunProperties`
- **Modules**: `client`, `host`, `plan`
- **`utils` module**: Re-exports `simvar_utils` functionality
- **`switchy`**: Underlying simulation and switching framework

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
simvar = { path = "../simvar" }

# Or with specific features
simvar = {
    path = "../simvar",
    features = ["async", "tcp", "time"]
}
```

## Usage

### Basic Simulation

```rust
use simvar::*;

struct MySimBootstrap;

impl SimBootstrap for MySimBootstrap {
    fn on_start(&self, sim: &mut impl Sim) {
        // Setup hosts and clients
        sim.host("my-host", || async {
            // Host logic
            Ok(())
        });
    }
}

fn main() {
    let results = run_simulation(MySimBootstrap).unwrap();
    // Process results
}
```

### With Utilities

```rust
#[cfg(feature = "utils")]
use simvar::utils;
```

## Feature Flags

By default, the `all` feature is enabled. Individual features can be selected:

- **`all`** (default): Enable the primary simulation feature set
- **`async`**: Async runtime support
- **`database`**: Database simulation
- **`fs`**: Filesystem simulation
- **`fs-simulator-real-fs`**: Enable real filesystem seeding helpers for simulator filesystem setup
- **`http`**: HTTP client/server simulation
- **`mdns`**: mDNS simulation
- **`random`**: Random number generation simulation
- **`tcp`**: TCP connection simulation
- **`telemetry`**: Telemetry support
- **`time`**: Time simulation
- **`tui`**: Terminal UI for simulation visualization
- **`upnp`**: UPnP simulation
- **`utils`**: Simulation utilities module
- **`web-server`**: Web server simulation
- **`pretty_env_logger`**: Pretty logging output
- **`fail-on-warnings`**: Treat warnings as errors

## Environment Variables

- **`SIMULATOR_RUNS`**: Number of simulation runs to execute (default: 1)
- **`SIMULATOR_MAX_PARALLEL`**: Maximum parallel runs (default: number of CPUs)
- **`NO_TUI`**: Disable terminal UI when set

## Dependencies

- **simvar_harness** (workspace): Core simulation testing framework
- **simvar_utils** (workspace, optional): Simulation utilities

## Integration

This package is designed for:

- **Deterministic Testing**: Predictable async test execution with controlled time and randomness
- **Concurrent Systems Testing**: Test multi-host, multi-client distributed systems
- **Regression Testing**: Reproducible test scenarios for complex async applications
- **Development**: Testing framework for async applications with simulated I/O

## Note

This package serves as a facade for the simulation variable system, re-exporting functionality from the core harness and providing optional utilities. The `simvar_harness` package provides the actual implementation of the simulation framework.