OrleansTestKit 8.2.1

Orleans TestKit

• Orleans TestKit
  • About
  • Getting Started
  • Contributing
    • Visual Studio
    • Visual Studio Code
  • Community
  • License

About

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.

Getting Started

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 OrleansTestKit

If 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.x

If 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.x

Refer to the unit tests project to learn how to create test fixtures using the Orleans TestKit.

Contributing

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.

Visual Studio

1. In Visual Studio, open the OrleansTestKit.sln solution.

2. Recommended: Install the CodeMaid extension.

Visual Studio Code

1. In Visual Studio Code, open the folder containing the OrleansTestKit.sln solution file.

2. Recommended: Open Visual Studio Code's extensions panel, and install all of the recommended extensions.

Community

• 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.

License

This project is released under the MIT license.