testing-guide
/testing-guide
Write tests for an FSH feature — xUnit + Shouldly + NSubstitute + AutoFixture, with naming and AAA conventions. Use when adding unit/handler/validator/entity tests. Full rules in .agents/rules/testing.md + integration-testing.md.
- Author
- fullstackhero ↗
- Repository
- dotnet-starter-kit ↗
- Licence
- MIT
- Last repository change
- 09.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Write tests for an FSH feature — xUnit + Shouldly + NSubstitute + AutoFixture, with naming and AAA conventions. Use when adding unit/handler/validator/entity tests. Full rules in .agents/rules/testing.md + integration-testing.md.
Original author description
Write tests for an FSH feature — xUnit + Shouldly + NSubstitute + AutoFixture, with naming and AAA conventions. Use when adding unit/handler/validator/entity tests. Full rules in .agents/rules/testing.md + integration-testing.md.
How it works
- Conventions
- Handler test
- Validator test
- Entity / domain test (no mocks)
- Architecture tests (guardrails — keep green)
- Integration tests
- Run
SKILL.md preview
---
name: testing-guide
description: Write tests for an FSH feature — xUnit + Shouldly + NSubstitute + AutoFixture, with naming and AAA conventions. Use when adding unit/handler/validator/entity tests. Full rules in .agents/rules/testing.md + integration-testing.md.
---
# Testing Guide
Stack: **xUnit** + **Shouldly** (`.ShouldBe`) + **NSubstitute** (`Substitute.For<>`) + **AutoFixture**
(`new Fixture()`). **Not** Moq, **not** FluentAssertions. Detailed conventions + integration-test gotchas
live in `.agents/rules/testing.md` and `.agents/rules/integration-testing.md`.
## Conventions
- Test class: `public sealed class {Sut}Tests`; SUT field named `_sut`.
- Method name: **`MethodName_Should_ExpectedBehavior[_When_Condition]`**.
- Arrange-Act-Assert with `// Arrange` / `// Act` / `// Assert`; group with `#region` (Happy Path / Guards / Edge Cases).
- Mocks via `Substitute.For<IService>()`; assert calls with `.Received(1).X(arg, Arg.Any<CancellationToken>())`.
- When asserting a forwarded `CancellationToken`, assert the **specific** token, not the default (NSubstitute fills optional params with `default`).
## Handler test
```csharp
public sealed class Create{Entity}CommandHandlerTests
{
private readonly {X}DbContext _db; // or Substitute.For<IService>() for service deps
private readonly Create{Entity}CommandHandler _sut;
private readonly IFixture _fixture = new Fixture();
public Create{Entity}CommandHandlerTests()
{
_db = /* in-memory or test DbContext */;
_sut = new Create{Entity}CommandHandler(_db);
}
[Fact]
public async Task Handle_Should_PersistEntity_And_ReturnId()
{
// Arrange
var command = new Create{Entity}Command(_fixture.Create<string>(), 9.99m, "USD");
// Act
var id = await _sut.Handle(command, CancellationToken.None);
// Assert
id.ShouldNotBe(Guid.Empty);
}
}
```
Service-dependency example (NSubstitute):
```csharp
_userService = Substitute.For<IUserService>();
// Act … then:
await _userService.Received(1).ToggleStatusAsync(true, command.UserId, Arg.Any<CancellationToken>());
```
## Validator test
```csharp
public sealed class Create{Entity}CommandValidatorTests
{
private readonly Create{Entity}CommandValidator _sut = new();
[Theory]
[InlineData("")]
public void Validate_Should_Fail_When_NameInvalid(string name)
{
var result = _sut.Validate(new Create{Entity}Command(name, 1m, "USD"));
result.IsValid.ShouldBeFalse();
result.Errors.ShouldContain(e => e.PropertyName == nameof(Create{Entity}Command.Name));
}
}
```
## Entity / domain test (no mocks)
```csharp
[Fact]
public void Create_Should_RaiseCreatedEvent()
{
var entity = {Entity}.Create("Test", Money.Zero());
entity.Id.ShouldNotBe(Guid.Empty);
entity.DomainEvents.ShouldContain(e => e is {Entity}CreatedDomainEvent);
}
```
## Architecture tests (guardrails — keep green)
`Architecture.Tests` (NetArchTest) enforce: module boundaries (cross-module refs only via `.Contracts`),
tenant-isolation rules, handlers `sealed`, and **every command/paginated-query handler has a validator**.
Don't weaken these to make a change pass — fix the code.
## Integration tests
`Integration.Tests` runs over real Postgres/Redis/RustFS via Testcontainers — **Docker required**. Set the
Finbuckle tenant context inline, rewire `IStorageService` post-registration for RustFS (S3), force long-polling
for SignalR. All detailed in `.agents/rules/integration-testing.md`.
## Run
```bash
dotnet test src/Tests/{X}.Tests
dotnet test src/Tests/Architecture.Tests
dotnet test src/FSH.Starter.slnx --collect "XPlat Code Coverage" --settings coverage.runsettings
```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · fullstackhero/dotnet-starter-kit | 100 | MIT |
| AsiaOstrich/universal-dev-standards | 100 | MIT |
| AsiaOstrich/universal-dev-standards | 100 | MIT |
| AsiaOstrich/universal-dev-standards | 100 | MIT |
| xonovex/platform | 100 | MIT |
| jamf-concepts/jamf-cli | 95 | MIT |
Database snapshot: 13.11.2026 · package version 011d13d3bc93 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100csharp-xunit
Write, review, or refactor C# unit tests using XUnit v3, NSubstitute, FluentAssertions, and Atc.Test. Use this skill whenever the user asks to create tests, add test coverage, fix failing tests, mock dependencies with NSubstitute, or follow the… - 100testing
Use before planning or performing work that requires tests, and when writing, editing, refactoring, or debugging tests anywhere under `tests/**` (unit, integration, or end-to-end); authoring NUnit 4 test classes (`*Test`, `*IntegrationTest`); using NSubstitute mocks, AutoFixture… - 100xunit-test-generator
Generate xUnit unit tests for C#/.NET code. Use this skill whenever the user shares a class, service, handler, or method and wants tests written, asks for unit tests, test coverage, "write tests for this", AAA tests, theory/data-driven tests, or mocking with Moq/NSubstitute.… - 100abp-testing
ABP Framework v10.x (10.4–10.6) testing: integration tests, *TestBase classes (Domain/Application/EntityFrameworkCore), SQLite in-memory, Shouldly, NSubstitute, data seeding, CurrentUser/CurrentTenant.Change, AddAlwaysAllowAuthorization. Use when you need to write unit/integration tests in ABP. - 100abp-testing
ABP Framework v10.x (10.4–10.6) testing quick reference: integration tests, *TestBase, SQLite in-memory, Shouldly, NSubstitute, data seeding, CurrentUser/CurrentTenant.Change. Use when you need to write tests in ABP. - 95xunit
xUnit.net testing framework with Fact, Theory, fixtures, DI, and mocking with Moq and NSubstitute. Covers .NET testing best practices. USE WHEN: user mentions "xUnit", ".NET testing", "Fact", "Theory", "InlineData", "Moq", "NSubstitute", "C# unit test" DO NOT USE FOR: NUnit -…