Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Polly-Contrib/Simmy/llms.txt

Use this file to discover all available pages before exploring further.

Simmy is a chaos-engineering and fault-injection library that integrates directly with Polly, the widely-used .NET resilience framework. Rather than waiting for real network failures, service outages, or unexpected latency spikes to reveal weaknesses in your fault-handling logic, Simmy lets you deliberately inject those conditions into any location where you already execute code through Polly. You can configure exactly how often an injection occurs, whether it is active at all, and even drive those decisions from external configuration at runtime — all without changing your core application logic.

​
Why chaos engineering matters

Building resilient .NET applications means doing more than writing retry and fallback policies. It means verifying that those policies actually behave correctly when the failures they guard against finally occur. The honest questions every resilience-focused team must answer are:
  • Is my system genuinely resilient enough, or does resilience only look good in code review?
  • Am I handling the right exceptions and the right edge-case scenarios?
  • What happens to my application when a key downstream dependency starts responding slowly — or not at all?
  • How can I test these scenarios without waiting for a real incident to happen in production?
Simmy answers all of these by making chaos a first-class policy inside your existing Polly setup. Because Simmy chaos policies participate in the same PolicyWrap mechanism as every other Polly policy, the rest of your resilience configuration — retries, timeouts, circuit breakers, fallbacks — continues to apply normally. You are testing the entire resilience stack together, exactly as it runs in production.

​
The four chaos policy types

Simmy provides four distinct chaos policies, each targeting a different failure mode:

Inject Exception

Throws a specified exception during a proportion of executions, letting you verify that your retry, circuit-breaker, and fallback policies react correctly to real exception types.

Inject Result

Substitutes a fabricated return value — such as an HttpResponseMessage with a 400 Bad Request status — so you can test how your code handles logically incorrect but non-exceptional responses.

Inject Latency

Adds an artificial delay before a call is placed, allowing you to validate that your timeout policies fire at the right thresholds and that slow dependencies do not cascade into wider outages.

Inject Behaviour

Executes any arbitrary action before a call is made, giving you a flexible hook to simulate infrastructure-level events such as restarting a virtual machine or invalidating a cache entry.

​
How Simmy integrates with Polly

Simmy chaos policies are ordinary Polly policies. You configure them with the fluent MonkeyPolicy builder and then use them anywhere you would use any other Polly policy — standalone or inside a PolicyWrap. The recommended pattern is to place the Simmy policy innermost inside a PolicyWrap. In that position, the chaos policy subverts the outbound call at the last possible moment (throwing a fault, returning a stubbed result, or adding latency), while the outer Polly policies — timeouts, retries, fallbacks, circuit breakers — still observe and react to whatever Simmy injects. This means you are genuinely testing how your existing resilience configuration responds to failures, not just testing Simmy in isolation. 
// Simmy policy sits innermost; outer Polly policies still fire normally
var policyWrap = Policy
    .Wrap(fallbackPolicy, retryPolicy, chaosPolicy);
All four chaos policy types are available in both synchronous and asynchronous variants, and every parameter — injection rate, enabled flag, fault value, latency duration — can be supplied as a static value or as a Func<Context, CancellationToken, T> delegate, enabling dynamic and context-targeted chaos control.

​
Compatibility

Simmy targets netstandard1.1, netstandard2.0, and netstandard2.1, and requires Polly v7.1.0 or later. It is compatible with any .NET runtime that supports one of those target frameworks, including .NET Framework 4.5+, .NET Core, and .NET 5+.
Target frameworkSupported
.NET Standard 1.1✅
.NET Standard 2.0✅
.NET Standard 2.1✅

​
Controlling chaos safely

Every Simmy policy exposes two complementary safety controls:
  • InjectionRate — a decimal between 0 and 1 representing the probability that chaos is applied on any given execution. A rate of 0.05 means roughly 5 % of calls are affected; 1 means every call is affected.
  • Enabled / EnabledWhen — a master switch that can be toggled independently of the injection rate. Even if the injection rate is 1.0, setting Enabled(false) (or returning false from an EnabledWhen delegate) means the policy does nothing at all.
Together, these two controls give you a fine-grained blast radius. You can ramp injection up gradually during a load test, tie the enabled flag to an environment variable or feature flag so chaos only runs in non-production environments, or use Context.OperationKey to target chaos at specific operations inside an otherwise healthy application.

Build docs developers (and LLMs) love

Get started for freeTalk to us