Values and Decisions
Why the platform looks the way it does. The conventions link here for their reasons: if a reason doesn’t apply to your project, the convention probably doesn’t either, and each convention explains how to opt out.
Values
| Value | What it means in practice |
|---|---|
| Adoptable piece by piece | Each pillar, package, build component and convention can be adopted on its own, in an existing repository, in small deployable steps. Nothing requires a rewrite. |
| Convention with an escape hatch | Defaults are opinionated so a new solution needs no decisions, and every default can be overridden: build parameters, overridable members, plain IServiceCollection entry points. |
| Pluggable | Packages with concrete services register them through an IDependencyInjectionModule or an IServiceCollection extension. Modules never assume a configuration section: options always come from the application. |
| Domain-free | Generic code takes strings and generic parameters instead of domain enums. Repositories, clients, event payloads, message destinations and UI environments stay in your applications. |
| Vendor-neutral | Company specifics plug in through extension points (DI-registered logging providers and metric recorders, options, configuration hooks) instead of being built in. |
| Standalone | Every dependency restores from nuget.org; test-only libraries are confined to the Testing.* kits. |
| Predictable at runtime | Settings are validated on start, failures have specific types, cancellation is honoured, and telemetry describes every call site the same way. |
| Explicit failures | A failure is identifiable by its type and message, and still catchable by the native .NET type callers already handle. |
| Automated, not documented | A rule that matters is checked by the build (layering, lint, warnings as errors, skills validation) rather than by review. |
Decisions
Architectural decision records, written after the fact for choices made while the toolkit grew. Each one records the context, the decision, its consequences and the alternatives considered.
| ADR | Decision |
|---|---|
| 0001 | Layered architecture, checked by the build |
| 0002 | Dependency-injection modules that receive their configuration |
| 0003 | One validated settings object per application |
| 0004 | Telemetry composed over the standard .NET logging and metrics APIs |
| 0005 | xUnit v3 on Microsoft.Testing.Platform |
| 0006 | Fallout for the build, without deployment components |
| 0007 | An in-process mock server instead of a MockServer container |
| 0008 | Three test levels, one project per level |
| 0009 | Optional automation preferences, precedence and stable public defaults |