Monica Application Unit Testing

Monica Application Unit Testing

Use sociable application tests for Monica-based business services. Boot the real Monica module graph once per service test project, replace only external seams, and resolve handlers, domain services, repositories, and module registrations from DI.

When To Use

• Create a Test.{ProductionProjectName} project for an application service.
• Migrate old NUnit/xUnit2/Moq/scratch tests into the new Test.* style.
• Test command handlers, query handlers, domain services, repositories, and module/service registration in a Monica application.
• Decide whether a test should use MonicaApplicationFixture or the fast-path ApplicationServiceFixture.
• Choose a database isolation strategy for application tests.

Workflow

1. Read the service's startup path first. Identify its module startup type or service runner and the DbContexts it registers.
2. Create one runnable test project per production project: src/Tests/Test.{ProductionProjectName} for business solutions or tests/Test.Monica.{Project} for Monica framework projects.

• {ProductionProjectName} is the exact .csproj file stem of the primary project under test.
• Examples: UserService.API -> Test.UserService.API; AlarmService.API -> Test.AlarmService.API; MessageService.Domain -> Test.MessageService.Domain.
• Do not shorten or normalize suffixes. Test.AlarmService is invalid when the production project is AlarmService.API.

1. Add CollectionFixtures/{Service}Collection.cs and {Service}TestFixture.cs. The fixture should derive from MonicaApplicationFixture when the service has a startup module.
2. Override fixture defaults only for boundaries:

• test databases
• distributed state
• event bus
• HTTP/RPC clients
• current user or tenant context

1. Keep test folders aligned with production folders: HandlersCommand, HandlersQuery, DomainServices, Repositories, Entities, and Modules.
2. In each sociable test, start with await using var scope = _app.NewScope(...), resolve the unit under test from the scope, pass scope.CancellationToken, and assert public behavior plus observable side effects.
3. Run the target test project with Windows paths under WSL. Run a single dotnet test process at a time.

Default Choice

Prefer MonicaApplicationFixture for application services because it catches real DI and module-wiring failures. Use ApplicationServiceFixture only for narrow fast-path handler tests where all collaborators are intentionally substituted and module boot would add noise.

Required Conventions

• Test project: Test.{ProductionProjectName} for business services, Test.Monica.{Project} for Monica framework projects.
• Test project folder, .csproj file name, assembly name, and RootNamespace must all use the same Test.{ProductionProjectName} value.
• Collection class: {Service}Collection with a public Name constant.
• Fixture class: {Service}TestFixture.
• Test class: {TypeUnderTest}Tests.
• Test method: Method_WhenCondition_ShouldExpectation.
• Field name for fixture in test classes: _app.
• Every sociable test class uses [Collection({Service}Collection.Name)].
• Entity invariant tests may instantiate entities directly and do not need a collection.

Hard Rules

• Replace boundaries, not domain logic.
• Do not use real network, real external databases, sleeps, or browser automation in unit tests.
• Do not mock constructors just to satisfy DI. Let the service provider build the real unit under test.
• Do not use abstract TestBase classes for new tests. Use fixture composition.
• Do not hide assertions in setup helpers. Builders can create data; tests must state the behavior being verified.
• Keep xUnit collection parallelism disabled for Monica application tests unless Monica module state has been proven isolated for parallel host boots.

Read As Needed

• references/standards.md
• Stable architecture and migration rules.
• references/templates.md
• Copyable UserService.API-based collection, fixture, handler, query-handler, repository, module, and entity test skeletons.
• references/database-isolation.md
• Choosing between per-scope SQLite, shared SQLite with transaction rollback, and real provider-backed database tests.

Validation

• dotnet test 'D:\Path\To\Solution\src\Tests\Test.{ProductionProjectName}\Test.{ProductionProjectName}.csproj'
• Run with --logger "console;verbosity=detailed" when checking fixture boot time.
• Treat warnings from the touched test project as failures. Existing application warnings may be documented separately when they are outside the migration scope.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Tairitsua
• Source: Tairitsua/Monica
• License: MIT
• Homepage: https://monica.dpdns.org/

Install and usage instructions live in the source repository linked above.