🐒 chaos_monkey_dart #

"If you don't break it first, production will — at the worst possible moment."

A production-grade chaos engineering package for Flutter & Dart.
Deliberately injects network delays, database failures, file corruption, memory
pressure, CPU spikes, and random exceptions to surface resilience weaknesses
before real users encounter them.

Inspired by Netflix Chaos Monkey (2011).
Staging & testing only. Never use in production.

Table of Contents #

• What is Chaos Engineering?
• Features
• Quick Start
• Presets
• Experiments
• Interceptors
• Reporters
• Scheduler
• API Reference
• Testing Utilities
• Safety
• Architecture
• FAQ

What is Chaos Engineering? #

Netflix invented Chaos Engineering in 2011 to validate that their distributed systems could survive unexpected failures. The core idea:

Deliberately inject failures in a controlled environment so you find weaknesses before your users do.

chaos_monkey_dart brings this battle-tested practice to Flutter & Dart apps.

Features #

Quick Start #

import 'package:flutter/foundation.dart';
import 'package:chaos_monkey_dart/chaos_monkey_dart.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  if (kDebugMode) {
    await ChaosMonkey.start(
      config: ChaosConfig(
        killDatabase:   0.05,    // 5%  — DB connection dies
        slowNetwork:    0.20,    // 20% — request delayed 10s
        networkDelayMs: 10000,
        dropNetwork:    0.03,    // 3%  — request dropped entirely
        throwRandomException: 0.02,
      ),
      isRelease: kReleaseMode,
    );
  }

  runApp(const MyApp());
}

Presets #

// Gentle — safe for daily CI pipelines
await ChaosMonkey.start(config: ChaosConfig.light());

// Moderate — weekly resilience gate checks
await ChaosMonkey.start(config: ChaosConfig.medium());

// Aggressive — dedicated resilience sprints
await ChaosMonkey.start(config: ChaosConfig.heavy());

// Apocalyptic — "Chaos Day" events only 🔥
await ChaosMonkey.start(config: ChaosConfig.nuclear());

Experiments #

NetworkChaos — HTTP delay & drop #

// Automatic (via Dio interceptor — see Interceptors section below)

// Manual wrapping:
final chaos = NetworkChaos(config: config);
try {
  final result = await chaos.applyTo(
    () => http.get(Uri.parse('https://api.example.com/users')),
    url: 'https://api.example.com/users',
    method: 'GET',
  );
} on NetworkDropException catch (e) {
  showErrorBanner('Network unavailable [${e.statusCode}]');
}

DatabaseChaos — kill / slow / corrupt #

final dbChaos = DatabaseChaos(config: config);

Future<User?> getUser(int id) async {
  try {
    return await dbChaos.wrap(
      () => db.findUser(id),
      label: 'UserDao.findUser',
    );
  } on DatabaseKillException {
    return _cache.get(id); // fallback to local cache
  }
}

LatencyChaos — any async call #

final latency = LatencyChaos(config: config);

// Works on BLE, SQLite, file I/O — anything async:
final data = await latency.wrap(
  () => bleDevice.readCharacteristic(),
  label: 'BLE.readCharacteristic',
);

ExceptionChaos — random exceptions #

final exChaos = ExceptionChaos(
  config: ChaosConfig(
    throwRandomException: 0.05,
    customExceptions: [
      AuthException('token expired'),
      RateLimitException('429 too many requests'),
    ],
  ),
);

final profile = await exChaos.wrap(
  () => userService.getProfile(userId),
  label: 'UserService.getProfile',
);

Interceptors #

Dio #

// Copy ChaosMonkeyDioInterceptor from example/lib/example_with_dio.dart
// (requires dio: ^5.4.0 in your pubspec)

final dio = Dio();
if (!kReleaseMode) {
  dio.interceptors.add(
    ChaosMonkeyDioInterceptor(
      config: ChaosConfig(
        slowNetwork: 0.20,
        networkDelayMs: 10000,
        dropNetwork: 0.05,
      ),
    ),
  );
}

http package #

// Copy ChaosAwareHttpClient from example/lib/example_with_http.dart
// (requires http: ^1.2.0 in your pubspec)

final client = ChaosAwareHttpClient(
  config: ChaosConfig(slowNetwork: 0.20, dropNetwork: 0.03),
);
final response = await client.get(Uri.parse('https://api.example.com'));

Reporters #

// Console (default) — coloured ASCII art
await ChaosMonkey.start(config: config, reporter: ConsoleReporter());

// File — JSON Lines
await ChaosMonkey.start(
  config: config,
  reporter: FileReporter(logPath: '/tmp/chaos_session.json'),
);

// Callback — custom observability pipeline
await ChaosMonkey.start(
  config: config,
  reporter: CallbackReporter(
    onEvent: (e) => analytics.track('chaos_event', e.metadata),
    onStopped: (r) => print('Session: ${r.totalEventsTriggered} events'),
  ),
);

// Collector — for test assertions
final collector = EventCollectorReporter();
await ChaosMonkey.start(config: config, reporter: collector);
// ... run test
await ChaosMonkey.stop();
expect(collector.eventsFor('NetworkChaos'), hasLength(greaterThan(0)));

// Multi — fan out to several reporters
await ChaosMonkey.start(
  config: config,
  reporter: MultiReporter([ConsoleReporter(), collector]),
);

Scheduler #

// Fixed interval (default — fires every 60s)
ChaosConfig(schedulerIntervalSeconds: 60)

// Random interval (more realistic)
final scheduler = RandomScheduler(
  experiments: myExperiments,
  minIntervalSeconds: 10,
  maxIntervalSeconds: 90,
  onEvent: handleEvent,
  isPausedCallback: () => ChaosMonkey.status().isPaused,
);

API Reference #

ChaosMonkey static methods #

Key config parameters #

Full parameter table: doc/configuration_guide.md

Testing Utilities #

import 'test/helpers/mock_helpers.dart';

// Always-trigger configs for deterministic tests:
final chaos = DatabaseChaos(config: alwaysKillDatabaseConfig());
expect(
  () => chaos.wrap(() async => 'result'),
  throwsA(isA<DatabaseKillException>()),
);

// Collect events during a test:
final events = await withChaosCollector(
  config: ChaosConfig(throwRandomException: 1.0, safetyGuard: false),
  body: () async => myService.doWork(),
);
expect(events.where((e) => e.experimentType == 'ExceptionChaos'), isNotEmpty);

Safety #

chaos_monkey_dart refuses to run in production by default.

// ✅ Safe — guard is active, release mode detected → throws
await ChaosMonkey.start(
  config: ChaosConfig(killDatabase: 0.05),
  isRelease: kReleaseMode, // kReleaseMode = true → ChaosInProductionException
);

// ✅ Safe — wrapped with debug check
if (kDebugMode) {
  await ChaosMonkey.start(config: config);
}

// ⚠️ Override — only if you have a custom staging-in-release setup
EnvironmentGuard.setCustomProductionCheck(() => myEnv.isProduction);

Full safety guide: doc/safety_guide.md

Architecture #

ChaosMonkey (controller)
    │
    ├── ChaosConfig (immutable settings)
    │
    ├── Experiments
    │   ├── NetworkChaos    ← HTTP delay/drop
    │   ├── DatabaseChaos   ← DB kill/slow/corrupt
    │   ├── FileChaos       ← File delete/corrupt
    │   ├── MemoryChaos     ← Heap pressure
    │   ├── CpuChaos        ← CPU spike
    │   ├── ExceptionChaos  ← Random throws
    │   └── LatencyChaos    ← Generic async delay
    │
    ├── Interceptors
    │   ├── ChaosDioInterceptor   ← Dio pipeline
    │   ├── ChaosHttpInterceptor  ← http package
    │   └── ChaosHttpClient       ← Drop-in http.BaseClient
    │
    ├── Reporters
    │   ├── ConsoleReporter       ← ANSI console
    │   ├── FileReporter          ← JSON Lines / text
    │   ├── CallbackReporter      ← User hooks
    │   ├── EventCollectorReporter← In-memory (tests)
    │   ├── MultiReporter         ← Fan-out
    │   └── SilentReporter        ← No-op
    │
    ├── Scheduler
    │   ├── ChaosScheduler        ← Fixed interval
    │   └── RandomScheduler       ← Random interval
    │
    └── Utils
        ├── Probability           ← roll / statistics
        ├── EnvironmentGuard      ← Production detection
        └── ChaosLogger           ← Structured logging

FAQ #

Q: Will this affect my release build?
A: No. With safetyGuard: true (default), the package throws if it detects kReleaseMode = true. Wrap with if (kDebugMode) for belt-and-braces safety.

Q: Can I use this with Riverpod / Bloc / GetX?
A: Yes — ChaosMonkey is framework-agnostic. Wrap your repository methods with the experiment classes regardless of state management choice.

Q: Does it work on web?
A: Network and exception chaos work everywhere. File, memory, and CPU chaos use dart:io and require native platforms.

Q: How do I get reproducible chaos in CI?
A: Pass seed: 42 (or any fixed integer) to ChaosConfig. Every call with the same seed produces identical outcomes.

Q: How do I disable chaos without removing code?
A: Set enabled: false in ChaosConfig. All experiments become silent no-ops.

License #

MIT — see LICENSE.

"chaos_monkey_dart doesn't break your app — it reveals what was already broken."