¶ NSubstitute (C#)
¶ Testing Technologies
/jpg/image.png)
NSubstitute is one of those libraries that quietly earns your trust as you begin to understand what good testing feels like. It doesn’t try to overwhelm you with flashy syntax, it doesn’t demand that you memorize obscure patterns, and it doesn’t force you into a particular way of structuring your code. Instead, it offers something far more valuable: a natural, expressive way to create test doubles in C#. It lets you write tests that read like the behavior you’re trying to describe, not like the machinery powering the test behind the scenes. That sense of clarity—of not fighting with your tools—is what makes NSubstitute such a beloved choice among C# developers.
This course—one hundred articles devoted to NSubstitute—is not about memorizing API calls or learning isolated tricks. It’s about understanding a way of working. It’s about learning how to test with confidence, how to design code with intention, and how to think in terms of interactions rather than mere implementation details. The aim is to help you not only master the library, but also develop a deeper instinct for writing clean, maintainable, behavior-focused tests.
Before we dig into the specifics of how NSubstitute works, it’s helpful to place it within the broader story of testing technologies. Testing in .NET has come a long way. Back in the early days, writing mocks or stubs felt tedious and repetitive. Developers often wrote their own fake implementations just to isolate logic, and those fakes tended to get tangled in maintenance as applications grew. When mocking frameworks started appearing, they solved a huge problem—but many of them came with steep learning curves, rigid syntax, or awkward method-chaining that felt unnatural to read.
NSubstitute took a fresh approach. It asked a simple question: what if interacting with a mock could feel like interacting with a real object? What if test doubles behaved so intuitively that you barely needed documentation? What if arranging behavior, verifying calls, and observing interactions could be done in plain, expressive code rather than abstract rule-based syntax?
That philosophy has shaped everything about NSubstitute. When you write tests with it, you’re not thinking about frameworks—you’re thinking about behavior. And that shift in mindset is part of the reason this course exists. We’re not here just to learn a library; we’re here to refine the craft of testing in a way that makes you a stronger C# developer.
We’ll begin with the basics—the heart of what NSubstitute offers. We’ll talk about substitutes: how to create them, how they respond to calls, how to set them up, and how to structure them so that your tests feel like natural descriptions of your system’s behavior. But we won’t stop at the mechanics. In these early explorations, we’ll take time to understand why NSubstitute works the way it does. Why its designers made certain decisions. Why its syntax feels conversational. Why its philosophy centers on writing tests that mirror human thought rather than technical implementation.
From there, we’ll move into the patterns that make mocking meaningful. Testing isn’t just about verifying that a piece of code runs; it’s about verifying that it behaves correctly in specific contexts. That often involves interactions between components—how your service talks to its dependencies, how your controllers coordinate logic, how your handlers react to external systems, how your repositories or adapters respond to requests. NSubstitute shines in these interaction-based tests because it lets you express expectations with subtlety and confidence.
A major theme early in the course will be understanding when to mock and when not to. Too many developers reach for mocks reflexively and end up with brittle, over-specified tests. Others avoid mocks entirely and end up testing huge sections of the system in a way that’s slow and hard to debug. The course will help you find the sweet spot—when fakes clarify behavior rather than distort it, and when interactions deserve explicit verification.
As we progress, we’ll dive deeper into call configuration. You’ll learn how to specify return values, how to use callbacks, how to simulate exceptions, how to track call sequences, and how to configure behavior dynamically. You’ll see how to handle methods with complex signatures, asynchronous behavior, tasks, value types, out parameters, ref parameters, and more. But each of these lessons will connect back to the core purpose of testing: clarity.
NSubstitute has a particularly elegant approach to call verification. Instead of writing abstract rules or multiple levels of setup, you simply assert that something happened. The syntax feels conversational:
myService.Received().DoSomething();
This reads like English. And as a result, your test suite becomes easier to read, easier to maintain, and easier to share with teammates. Throughout the course, we’ll explore how to use verification responsibly—how to avoid overspecifying behavior, how to prevent fragile tests, and how to verify interactions in a way that prioritizes intentions over implementation details.
We’ll also examine argument matching—one of the most powerful features of NSubstitute. Whether you’re verifying that a dependency received a call with certain parameters or configuring return values for particular inputs, the ability to express expectations flexibly is essential. You’ll learn how to match arguments with precision, how to use lambdas for more complex scenarios, and how to keep your verification focused on meaning rather than noise.
A major portion of the course will focus on how NSubstitute fits into modern C# testing ecosystems. Whether you’re using xUnit, NUnit, or MSTest, NSubstitute adapts smoothly. The course will walk through common workflows, best practices, and recommended patterns to structure test suites cleanly. You’ll learn how to break tests into logical groups, how to apply naming conventions that make sense, how to organize your fixtures thoughtfully, and how to ensure your suite stays fast, reliable, and readable.
We’ll also dig deeply into mocking frameworks’ relationship with software design. Good tests often reveal design issues. If your code is hard to mock, it’s probably too tightly coupled. If your tests are filled with complicated setups, your abstractions may be leaking. NSubstitute is particularly good at highlighting these problems because it expects your code to be modular, interface-driven, and clearly separated. Over the course of these articles, you’ll start to see how using NSubstitute improves your design instincts. It encourages you to think in terms of boundaries, responsibilities, and clear contracts.
Another important theme will be test doubles of various kinds. While NSubstitute specializes in mocks, stubs, and spies, understanding the broader landscape of test doubles will help you make better decisions. Throughout the course, we’ll explore when to use:
– substitutes
– real implementations
– fakes
– in-memory stores
– partial mocks
– hand-written stubs
and how these choices affect the clarity and reliability of your suite.
We’ll also spend time exploring advanced workflows. For example:
– mocking asynchronous flows
– substituting event-based dependencies
– mocking chains of method calls
– using NSubstitute in dependency injection setups
– mocking static behavior through adapters
– handling generic methods elegantly
– creating substitutes for classes using wrappers
As the course deepens, we’ll look at real-world scenarios. How do you mock database contexts in layered architectures? How do you simulate external services in integration-heavy systems? How do you test domain logic without tying your tests to infrastructure? How do you handle behavior that spans multiple interactions? These practical scenarios will help you understand NSubstitute in the context of real applications, not just isolated unit tests.
There will be a significant section dedicated to troubleshooting and preventing common mistakes—things like overuse of Received(), misconfigured arguments, fragile test setups, mismatched expectations, and subtle timing issues. You’ll learn how to spot these problems early, how to design your tests so that failures are meaningful rather than confusing, and how to keep your suite healthy over time.
And then there’s maintainability—perhaps the most important theme in the entire series. A test suite is a long-term investment. Tests that are fast, expressive, and stable today must remain so a year from now. NSubstitute encourages good habits naturally, but using it well means thinking ahead. Throughout the course, we’ll explore patterns for keeping your test suite organized, avoiding duplication, reducing noise, and building utilities that support clean testing across your entire codebase.
Finally, in the last stretch of the course, we’ll put all the concepts together to create a holistic understanding of NSubstitute—not just how to use it, but how to think with it. How to reason about interactions. How to craft behavior specifications that reflect real-world requirements. How to write tests that build confidence in both your code and your design. By the time you finish, NSubstitute won’t feel like a framework you “use.” It will feel like a conversational tool that helps you express exactly what your software should do.
The ultimate goal of this course is simple: to help you become a more thoughtful, confident, and expressive developer. NSubstitute is the tool, but the craft is yours. As you grow more comfortable with the library, you’ll begin to see testing as less of a burden and more of a natural part of building quality software—a place where clarity matters, where behavior takes priority, and where confidence comes from understanding, not luck.
So settle in. This won’t be a rushed journey. We’ll explore NSubstitute with patience, with curiosity, and with an eye toward improving the way you think about code.
Let’s begin.
¶ NSubstitute (C#)
¶ Introduction to NSubstitute
1. Introduction to Mocking Frameworks in Unit Testing
2. Getting Started with NSubstitute
3. Installing NSubstitute in Your C# Project
4. Understanding Mocking and Stubbing Concepts
5. Exploring the Benefits of NSubstitute for Unit Testing
6. The Basics of Test-Driven Development (TDD) with NSubstitute
¶ Getting Comfortable with NSubstitute
7. Creating Your First Mock with NSubstitute
8. Working with Interfaces and Abstract Classes
9. Setting Up Simple Substitutes
10. Return Values and Setting Up Responses
11. Verifying Calls with NSubstitute
12. Handling Properties with NSubstitute
¶ Basic Mocking Techniques
13. Stubbing Method Calls with NSubstitute
14. Using Arg.Any to Match Arguments
15. Returning Custom Values with Arg.Is
16. Handling Multiple Returns for Method Calls
17. Configuring Substitutes to Throw Exceptions
18. Verifying Method Invocations with Received()
19. Simulating Time-Dependent Code with NSubstitute
20. Working with Delegates and Events
¶ Intermediate Techniques
21. Mocking Asynchronous Methods with NSubstitute
22. Handling Async and Await with NSubstitute
23. Using Callbacks to Capture Arguments
24. Implementing Behavior with Do()
25. Matching Arguments More Precisely with ArgMatchers
26. Mocking Generics with NSubstitute
27. Using Arg.ForAny() for Advanced Argument Matching
28. Using Received() for Multiple Call Verifications
29. Handling Out and Ref Parameters
30. Creating and Testing Custom Substitutes
¶ Advanced Mocking and Best Practices
31. Complex Argument Matching with Custom Matchers
32. Working with Sealed Classes in Unit Testing
33. Creating Substitutes for Events and Event Handlers
34. Verifying Call Order with NSubstitute
35. Mocking Time and Date Using NSubstitute
36. Using NSubstitute with Dependency Injection
37. Best Practices for Test-Driven Development with NSubstitute
38. Mocking Static Methods with NSubstitute
39. Working with Substitutes in Multithreaded Applications
40. Testing Legacy Code with NSubstitute
¶ Mocking Real-World Scenarios
41. Mocking Web API Calls in Unit Tests
42. Mocking Database Calls with NSubstitute
43. Mocking File System Operations
44. Mocking External Service Dependencies
45. Creating Test Doubles for Third-Party Libraries
46. Mocking Authentication and Authorization Logic
47. Testing Web Requests with NSubstitute
48. Mocking UI Components for Unit Tests
49. Mocking Complex Workflows and Pipelines
50. Simulating Network Latency and Failures in Tests
¶ Mocking Patterns and Design
51. Mocking for Loose Coupling in Unit Tests
52. The Law of Demeter and Mocking Practices
53. Using the Façade Pattern with NSubstitute
54. Mocking for Decoupling Infrastructure from Logic
55. Writing Unit Tests for IoC Containers and Factories
56. Applying the Test Double Pattern with NSubstitute
57. Using NSubstitute for Boundary Testing
¶ Debugging and Troubleshooting
58. Troubleshooting Failed Verifications in NSubstitute
59. Using NSubstitute's Diagnostic Features
60. Understanding and Fixing Common NSubstitute Issues
61. How to Avoid Over-Mocking in Unit Tests
62. Identifying Unnecessary Mocking and Refactoring Tests
63. Debugging Test Failures with Stack Traces and NSubstitute
¶ Optimizing NSubstitute Tests
64. Reducing Mocking Overhead in Your Tests
65. Speeding Up Tests by Minimizing Mock Setup
66. Best Practices for Structuring NSubstitute Tests
67. Testing with NSubstitute in Continuous Integration Pipelines
68. Mocking Performance Considerations in Large Codebases
¶ Integrating with Other Testing Frameworks
69. Integrating NSubstitute with MSTest
70. Using NSubstitute with NUnit for Advanced Testing
71. Working with xUnit and NSubstitute for Unit Testing
72. Combining NSubstitute with FluentAssertions for Better Assertions
73. Integrating NSubstitute with SpecFlow for Behavior-Driven Development
74. Combining NSubstitute with AutoFixture for Automated Test Data Generation
¶ Refactoring and Advanced Testing Techniques
75. Refactoring Legacy Tests Using NSubstitute
76. Mocking for Behavior Verification in Functional Tests
77. Creating a Mocking Strategy for Large Applications
78. Handling Dependency Cycles in Unit Tests
79. Combining Multiple Mocks for Complex Scenarios
80. Writing Isolated Tests with NSubstitute and Test Doubles
¶ Using NSubstitute in Real Projects
81. Building Reliable Unit Tests for Web Applications
82. Writing Tests for APIs with External Calls
83. How to Write Mocking Code in Microservices
84. Testing Service Layer Logic with NSubstitute
85. Mocking Complex Business Logic for Enterprise Applications
86. Unit Testing Domain Models Using NSubstitute
¶ Advanced Concepts
87. Working with NSubstitute's Internal Calls
88. Advanced Argument Matching and Custom Matchers
89. Creating Custom Substitutes for Abstract Classes
90. Mocking Static Properties and Fields
91. Using NSubstitute for Simulating Complex UI Logic
92. Handling Multiple Dependencies in Tests
¶ NSubstitute in Production and Testing Strategies
93. When to Use NSubstitute vs Other Mocking Frameworks
94. NSubstitute’s Role in Test Strategy and Test Architecture
95. Managing NSubstitute Substitutes in Large Teams
96. Scaling Unit Tests with NSubstitute in Big Codebases
97. Designing Effective Unit Tests Using NSubstitute
98. When Mocking Goes Wrong: Common Pitfalls to Avoid
99. Building a Robust Mocking Strategy for Testing External APIs
100. Final Thoughts: Mastering NSubstitute for Professional Unit Testing