# Chaos Control - Making Random Testable

> See how to take advantage of Random.Shared in your C# code while also making it testable.

- URL: https://blog.nimblepros.com/blogs/chaos-control-making-random-testable/
- Author: [Scott DePouw](https://blog.nimblepros.com/authors/scott/)
- Published: 2024-12-09
- Categories: [Software Development](https://blog.nimblepros.com/categories/software-development/)
- Publisher: [NimblePros](https://blog.nimblepros.com/)

---

Yes, it is in fact possible to test randomness within your application! Like with so many other facets of your code, it's important too. Whether you're making a complex game or a simple random featured item selector on a web page, verifying that your code behaves properly given random input is essential. Let's see what we can do with some of what C# has to offer in terms of random features.

## Random.Shared

A lot of C# developers will see the [`System.Random` class](https://learn.microsoft.com/en-us/dotnet/api/system.random) on a cursory search for "how do I get a random outcome" and get straight to using it. Out of the box it'll get what you want easily! For a random number, one merely provides a range of values to `myRandomInstance.Next()` and it's yours. Many will then go on to ask "how do I manage my instances of the `Random` class efficiently?" Should you maintain a single static instance? New one up every time you need it?

Well, as of .NET 6, the framework provides the answer for you. The `Random` class has a static, thread-safe instance of itself, accessible via a property called [`Shared` on the `Random` class](https://learn.microsoft.com/en-us/dotnet/api/system.random.shared). Anywhere in your code you can call `System.Random.Shared.Next()` and be off to the races with whatever random numbers you need. No more managing instances of `Random` on your own!

As of .NET 8, if you're needing random elements out of an array or other `ReadOnlySpan<T>`, [`GetItems()` has you covered](https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems). Prior to this, you'd have to write code akin to `var randomItem = items[random.next(0, items.Length)];` to pull a random element out of an array. I strongly suspect this is why `Random.Next(int minValue, int maxValue)` treats `maxValue` as an *exclusive* upper bound, as otherwise you'd have to write `items.Length - 1`.

So, we have our instance of `Random`. How do we test it?

## Static Cling

Accessing a global static instance of anything, `Random` or otherwise, makes code harder to test. This is a code smell known as [Static Cling](https://deviq.com/antipatterns/static-cling). Consider the following.

```csharp
using System;

namespace SuperCoolRPG;

public class BattleCalculator
{
  public int CalculateDamage(int weaponStrength, int characterStrength)
  {
    return weaponStrength + characterStrength + Random.Shared.Next(5, 31);
  }
}
```

Getting the amount of damage dealt by a character's attack here is a simple formula: Add the strengths up alongside a random value between 5 and 30 (recall the 2nd parameter is an exclusive upper bound). This is a pretty simple calculation, but real games have far more complex math going on. For example, the [damage calculation in Pokémon](https://bulbapedia.bulbagarden.net/wiki/Damage) has far more inputs and operations happening. We'd like to unit test our calculations for various random results to make sure our game is properly balanced and doesn't give off the wall results.

To accomplish this, we're going to take our shared instance of `Random` and [Wrap It Up](https://blog.nimblepros.com/blogs/wrap-it-up/)!

## Controlling Chaos with an Abstraction for Random

`Random` has a myriad of methods available (including the static `Shared` property even). When one creates an interface to be used for dependency injection, one only needs to provide what's being used. It can be daunting and exhaustive to try and wrap and mirror everything. For our class, we only use one overload of `Next()`, so that's all we'll do for now. We can always add additional implementations as needed later.

```csharp
public interface IRandom
{
  /// <inheritdoc cref="System.Random.Next(int,int)" />
  int Next(int minValue, int maxValue);
}

public class SystemRandom : IRandom
{
  /// <inheritdoc />
  public int Next(int minValue, int maxValue) => System.Random.Shared.Next(minValue, maxValue);
}
```

### Using "inheritdoc" to Spill the Beans

Our wrapper class `SystemRandom` just calls to the `Shared` instance to do real randomization. Our interface exposes the documentation available to the real `Next()` method using `inheritdoc`, with `cref` pointing to the original method. This will maintain the documentation when wanting to discover details about the method when you're working in an IDE like Visual Studio or JetBrains Rider. No need to copy and paste! We do this because we know there's just one implementation of `IRandom` (a wrapping class of `System.Random`). If there existed multiple `IRandom` implementations it would be inaccurate to use `System.Random.Next`, but because we know it always will be, we can allow our interface to "know about the implementation details" for the sake of making the documentation easier to read when using `IRandom`.

## Using the Abstraction

Let's modify our `BattleCalculator` with our new interface.

```csharp
public class BattleCalculator(IRandom random)
{
  public int CalculateDamage(int weaponStrength, int characterStrength)
  {
    return weaponStrength + characterStrength + random.Next(5, 31);
  }
}
```

Nothing changes about the real behavior. In fact, you could write integration tests for various scenarios by simply providing a new instance of `SystemRandom` to the `BattleCalculator` constructor. But of course we're here to control the chaos of randomization! Now that we have our `IRandom` interface, it's trivial to mock it using your mocking tool of choice, and test to your heart's content.

Here's an example using [NSubstitute](https://nsubstitute.github.io/).

```csharp
using FluentAssertions;
using NSubstitute;
using SuperCoolRPG;

namespace SuperCoolRPGTests.BattleCalculatorTests;

public class CalculateDamage
{
  private readonly IRandom _mockRandom = Substitute.For<IRandom>();
  private readonly BattleCalculator _calculator;

  public CalculateDamage()
  {
    _calculator = new(_mockRandom);
  }

  [Fact]
  public void AddsRandomValueToDamage()
  {
    const int randomValue = 50;
    const int weaponStrength = 95;
    const int characterStrength = 5;
    _mockRandom.Next(Arg.Any<int>(), Arg.Any<int>()).Returns(randomValue);

    int damage = _calculator.CalculateDamage(95, 5);

    damage.Should().Be(weaponStrength + characterStrength + randomValue);
  }
}
```

Had we been stuck with real randomization, there's no way we could have written the above test. Well, to be precise, we could have written it, but it would have failed most of the time! But since we controlled randomization in our application via interface, we now have the capability of controlling randomization to validate any assertions we want to make about our code's behavior.

## Happy Holidays!

That'll do it for my blog posts this year. Happy holidays, everyone!
