feat: Add NSubstitute documentation covering skill usage, core API, async handling, project patterns, and common mistakes

Author: aalmada

.github/skills/nsubstitute/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: nsubstitute
+description: Use NSubstitute to create test doubles (mocks/stubs/spies) for .NET interfaces and classes, covering Substitute.For<T>, Returns/ReturnsForAnyArgs, Received/DidNotReceive, Arg matchers, async Task stubbing, callbacks, and partial substitutes. Always trigger when the user writes, reviews, or asks about mocking, faking dependencies, Substitute.For, Received(), DidNotReceive(), Arg.Any, Arg.Is, test doubles, verifying interactions, setting up shared mock infrastructure, or stubbing async methods in .NET tests — even if they don't mention NSubstitute by name. Prefer this skill over guessing; NSubstitute's argument matcher rules, the discard pattern for Returns(), async Task<T> type inference, nested interface substitution (e.g., Marten's IDocumentSession.Events), and partial substitute pitfalls all have non-obvious failure modes that are easy to get wrong.
+---
+
+# NSubstitute Skill
+
+NSubstitute (v5) is the mocking library used in this project. It creates in-memory test doubles for interfaces (and optionally classes) with a fluent, readable API.
+
+## Quick-start anatomy
+
+```csharp
+using NSubstitute;
+
+// 1. Create — always prefer interfaces over classes
+var emailService = Substitute.For<IEmailService>();
+
+// 2. Stub — discard result with _ = to satisfy the compiler
+_ = emailService.SendAsync(Arg.Any<string>()).Returns(Task.CompletedTask);
+
+// 3. Execute the system under test
+await handler.Handle(command);
+
+// 4. Assert interactions
+await emailService.Received(1).SendAsync("user@example.com");
+await emailService.DidNotReceive().SendAsync(Arg.Is<string>(s => s.Contains("admin")));
+```
+
+Key rules at a glance:
+- **Discard return of `.Returns()`**: assign to `_ =` to avoid compiler warnings.
+- **Never use arg matchers in real calls**: only in `.Returns(...)`, `.Received()`, or `.When(...).Do(...)`.
+- **Await async `.Received()` calls**: NSubstitute tracks `async Task` calls — the assertion itself is synchronous, but the method signature needs `await` to compile.
+
+---
+
+## Reference files — read before writing code
+
+| Topic | File |
+|-------|------|
+| Creating substitutes, Returns, Received, Arg matchers | [references/api.md](references/api.md) |
+| Async, exceptions, callbacks, events, partial subs | [references/async-and-advanced.md](references/async-and-advanced.md) |
+| BookStore project patterns (HandlerTestBase, nested interfaces) | [references/project-patterns.md](references/project-patterns.md) |
+
+---
+
+## Common mistakes
+
+```
+✅ _ = sub.Method().Returns(value)        ❌ sub.Method().Returns(value)  // compiler warning
+✅ sub.Received().Method(Arg.Any<T>())    ❌ sub.Method(Arg.Any<T>())     // matcher in real call
+✅ Substitute.For<IService>()             ❌ Substitute.For<ConcreteClass>()  // non-virtual not intercepted
+✅ sub.Method().Returns<string>(x => ...) ❌ sub.Method().Returns(x => ...) // CS0121 on Task<T>
+✅ await emailSvc.Received(1).SendAsync() ❌ emailSvc.Received().SendAsync()  // forgetting await
+```

.github/skills/nsubstitute/references/api.md

@@ -0,0 +1,108 @@
+# NSubstitute Core API Reference
+
+## Creating substitutes
+
+```csharp
+// Interface (recommended)
+var service = Substitute.For<IEmailService>();
+
+// Multiple interfaces
+var cmd = Substitute.For<ICommand, IDisposable>();
+
+// Class (only virtual members are intercepted — use with care)
+var reader = Substitute.For<SomReader>("ctor-arg");
+
+// Delegate
+var transform = Substitute.For<Func<string, int>>();
+transform("hello").Returns(42);
+
+// Partial substitute (real methods run unless configured)
+var partial = Substitute.ForPartsOf<MyClass>();
+partial.Configure().SomeVirtual().Returns("stubbed"); // use Configure() to avoid running real code
+```
+
+The `Substitute.ForPartsOf<T>()` trap: calling `partial.SomeVirtual().Returns(...)` without `Configure()` **actually invokes the real method** during setup, causing side effects. Always use `partial.Configure().Method()` first.
+
+---
+
+## Setting return values
+
+```csharp
+// Fixed value
+_ = service.GetUserAsync(userId).Returns(user);
+
+// Value based on arguments (CallInfo)
+_ = service.GetAsync(default).ReturnsForAnyArgs(x => new User { Id = x.Arg<Guid>() });
+
+// Sequence of values (each call gets the next)
+_ = cache.Get<string>("key").Returns("first", "second", "third");
+
+// Sequence with exceptions
+_ = calculator.Mode.Returns("DEC", "HEX", x => { throw new Exception("exhausted"); });
+
+// Property
+_ = httpContextAccessor.HttpContext.Returns(new DefaultHttpContext());
+```
+
+`Returns(value)` is argument-specific: it only matches calls with those exact arguments. Use `ReturnsForAnyArgs(value)` (or `Arg.Any<T>()` matchers) when you don't care which arguments are passed.
+
+---
+
+## Argument matchers
+
+Matchers are valid **only inside Return/Received/When.Do** calls — never in real production calls.
+
+```csharp
+// Match anything
+service.Send(Arg.Any<string>()).Returns(true);
+
+// Match with predicate
+service.Send(Arg.Is<string>(s => s.StartsWith("admin"))).Returns(false);
+
+// Capture argument for inspection
+var captured = default(string);
+service.Send(Arg.Do<string>(x => captured = x)).Returns(true);
+
+// out parameters
+lookup.TryLookup("key", out Arg.Any<string>())
+      .Returns(x => { x[1] = "value"; return true; });
+```
+
+---
+
+## Verifying calls
+
+```csharp
+// Received exactly N times (default = once or more if no arg given)
+service.Received(1).Send("hello@example.com");
+
+// Received any number of times
+service.Received().Send(Arg.Any<string>());
+
+// Not received
+service.DidNotReceive().Send("admin@example.com");
+
+// Received with any args (ignores argument values entirely)
+service.ReceivedWithAnyArgs().Send(default);
+
+// Property getter / setter
+_ = cache.Received().Get<User>("key");
+cache.Received().Size = Arg.Is<int>(n => n > 0);
+
+// Indexers
+dictionary.Received()["key"] = Arg.Is<int>(v => v > 0);
+```
+
+The `Received()` chain returns a proxy — access the member on it to declare what you expected. This is purely declarative; the framework inspects the recorded calls and throws `ReceivedCallsException` if the expectation isn't met.
+
+---
+
+## Clearing and resetting
+
+```csharp
+// Clear recorded calls (but keep stubs)
+sub.ClearReceivedCalls();
+
+// Clear both calls and stubs
+sub.ClearSubstitute(ClearOptions.All);
+```

.github/skills/nsubstitute/references/async-and-advanced.md

@@ -0,0 +1,105 @@
+# NSubstitute — Async, Exceptions, Callbacks, Events
+
+## Async methods (Task / Task<T> / ValueTask)
+
+NSubstitute handles async methods transparently — `.Returns()` accepts both synchronous values and Tasks.
+
+```csharp
+// Stub returning a value
+_ = service.GetUserAsync(id).Returns(user);          // auto-wrapped in Task
+
+// Stub returning Task.CompletedTask (void async)
+_ = service.SendAsync(email).Returns(Task.CompletedTask);
+
+// Stub returning null (explicit generic needed to avoid CS0121)
+_ = service.FindAsync(id).Returns((User?)null);
+
+// Throw inside a Returns callback — must specify the type explicitly (CS0121 workaround)
+_ = service.GetAsync(id).Returns<User>(x => { throw new NotFoundException(); });
+
+// Verify async call
+await service.Received(1).GetUserAsync(id);
+```
+
+**CS0121 tip**: When a method returns `Task<T>` and you pass a lambda that throws, the compiler can't resolve which `Returns` overload to use. Write `Returns<T>(x => { throw ... })` with the explicit generic parameter.
+
+---
+
+## Throwing exceptions
+
+```csharp
+// Synchronous throw on method call
+service.When(x => x.Process(Arg.Any<Order>()))
+       .Do(x => { throw new InvalidOperationException("failed"); });
+
+// Or using Throws extension (requires NSubstitute.Extensions or direct When/Do)
+service.When(x => x.Delete(Arg.Any<Guid>()))
+       .Throw(new UnauthorizedException());
+
+// Throw on async method
+_ = service.GetAsync(id).Returns<User>(_ => throw new NotFoundException());
+```
+
+---
+
+## Callbacks and side effects
+
+Use callbacks when you need side effects beyond a return value — for example, capturing arguments, simulating state mutations, or tracking invocation counts.
+
+```csharp
+// Capture argument via Arg.Do
+var sentEmails = new List<string>();
+_ = emailService.SendAsync(Arg.Do<string>(addr => sentEmails.Add(addr)))
+                .Returns(Task.CompletedTask);
+
+// Run code on every call using When...Do (good for void methods)
+var callCount = 0;
+service.When(x => x.Notify(Arg.Any<string>()))
+       .Do(x => callCount++);
+
+// AndDoes — side effect alongside a return value
+_ = service.Process(Arg.Any<Order>())
+           .Returns(Result.Ok())
+           .AndDoes(x => Console.WriteLine($"Processed {x.Arg<Order>().Id}"));
+
+// Callback builder for sequenced behaviour
+service.When(x => x.Run())
+       .Do(Callback
+           .First(x => Console.WriteLine("first call"))
+           .Then(x => Console.WriteLine("second call"))
+           .ThenKeepDoing(x => Console.WriteLine("subsequent")));
+```
+
+**When to use `When...Do` vs `Returns + AndDoes`**: prefer `Returns + AndDoes` for non-void methods (cleaner). Use `When...Do` for `void` methods or when you need complex sequenced behaviour via `Callback`.
+
+---
+
+## Events
+
+```csharp
+// Subscribe and raise event
+var command = Substitute.For<ICommand>();
+command.Executed += Raise.Event();                        // EventHandler
+command.DataReceived += Raise.Event<DataEventArgs>(args); // EventHandler<T>
+
+// Verify subscription
+command.Received().Executed += Arg.Any<EventHandler>();
+```
+
+---
+
+## Partial substitutes
+
+Use `ForPartsOf<T>` when you want real behaviour for most methods but need to stub one dependency-heavy or side-effectful method.
+
+```csharp
+var reader = Substitute.ForPartsOf<FileReader>();
+
+// MUST call Configure() first — otherwise the real method runs during setup
+reader.Configure().ReadFile("data.csv").Returns("1,2,3");
+
+// Now the real Read() will call the stubbed ReadFile()
+var result = reader.Read("data.csv");
+```
+
+Only works for `virtual` methods. Non-virtual code always runs as-is; use NSubstitute.Analyzers to catch this at compile time.