The Orleans TestKit is a community-maintained library providing mock objects that facilitate unit testing grains in applications built on the Microsoft Orleans framework. It provides a simulated grain activation context, leveraging Moq to generate test doubles for dependencies such as persistent state, reminders, timers, and streams. By simulating a grain activation context, you focus on testing the behavior of a single grain in isolation.
The official integration testing approach leverages the TestCluster. The TestCluster is a fully functional, in-memory cluster. It is faster to start than a regular cluster and provides a complete runtime. However, it may require complex configuration and custom-developed dependencies to test particular scenarios. That having been said, there are important caveats to the Orleans TestKit approach.
The simulated grain activation context does not provide the single-threaded execution model of the Microsoft Orleans runtime. It is up to you to ensure the grain activation is used appropriately. Unfortunately, this may result in abnormal method execution or behaviors that are impossible to reproduce, especially in reentrant grains.
It is also important to note that mock-based testing presents risk of coupling your test cases to the internal implementation details of the grain. This may make your code difficult to refactor and your tests brittle (see Martin Fowler's article Mocks Aren't Stubs).
It is recommended that you consider developing a mixture of tests based on both the Orleans TestKit and the TestCluster.
There are three branches and major versions of the Orleans TestKit. The main branch provides Orleans TestKit 8, a stable version supporting Orleans 8. The 4.x branch provides Orleans TestKit 4, a stable version supporting Microsoft Orleans 7 (during development, it was known as Orlean 4). The 3.x branch provides Orleans TestKit 3, a stable version supporting Microsoft Orleans 3.
If you are using Microsoft Orleans 8, install the latest, stable OrleansTestKit NuGet package in your test project. For example, run the following command in your Visual Studio Package Manager Console:
Install-Package OrleansTestKitIf you are using Microsoft Orleans 7, install the latest, stable version less than 8.0 of the OrleansTestKit NuGet package in your test project. For example, run the following command in your Visual Studio Package Manager Console, replacing 4.x.x with the latest version of the NuGet package less than 8.0:
Install-Package OrleansTestKit -Version 4.x.xIf you are using Microsoft Orleans 3, install the latest, stable version less than 4.0 of the OrleansTestKit NuGet package in your test project. For example, run the following command in your Visual Studio Package Manager Console, replacing 3.x.x with the latest version of the NuGet package less than 4.0:
Install-Package OrleansTestKit -Version 3.x.xRefer to the unit tests project to learn how to create test fixtures using the Orleans TestKit.
Either Visual Studio or Visual Studio Code may be used for development. Visual Studio provides a richer experience, especially when it comes to debugging. Visual Studio Code providers a lightweight experience and still works with the majority of the tooling.
-
In Visual Studio, open the
OrleansTestKit.slnsolution. -
Recommended: Install the CodeMaid extension.
-
In Visual Studio Code, open the folder containing the
OrleansTestKit.slnsolution file. -
Recommended: Open Visual Studio Code's extensions panel, and install all of the recommended extensions.
- Chat about all things Orleans on the official Discord server.
- Report bugs and ask questions about the Orleans TestKit by opening a new GitHub Issue. Please be sure to note which version of the Orleans TestKit you are using.
This project is released under the MIT license.