XBullet.EasyTesting documentation

XBullet.EasyTesting provides composable infrastructure for integration testing ASP.NET Core applications, distributed applications, Azure Functions, external dependencies, and observable side effects. All packages target .NET 8, .NET 9, and .NET 10.

Use this page to choose the smallest set of packages for a testing goal. The detailed documentation is being expanded according to the documentation roadmap; links below lead to the best current guide or package README.

Use the searchable API reference when you know the package, namespace, type, or member you need.

Start here

If you are testing an ASP.NET Core endpoint for the first time:

  1. Install XBullet.EasyTesting.
  2. Follow the first controller test to create an authenticated factory, scenario scope, client, request, and assertion.
  3. Give each test an isolated scenario when it changes application state; see scenarios and isolation.
  4. Add extension packages only for the external boundaries that the test needs.

The core package supports both Program-based and Startup-based applications. It can simulate identities inside TestServer or send credentials through the application's real authentication handlers. These are different kinds of tests: simulated authentication is fast and focused, while end-to-end authentication validates token, certificate, or API-key handling.

Find documentation by goal

I want to... Start with Package
Test an authenticated controller Run your first controller test XBullet.EasyTesting
Isolate setup and cleanup for every test Scenarios and isolation XBullet.EasyTesting
Test a Startup-based application without executing Program.Main Choose a test host XBullet.EasyTesting
Test multiple authentication schemes Authentication models XBullet.EasyTesting
Exercise production authentication handlers Configure end-to-end handlers XBullet.EasyTesting
Replace services or configuration Override services and configuration XBullet.EasyTesting
Assert status, headers, or JSON Assert controller responses XBullet.EasyTesting
Seed or inspect an EF Core database Test with Entity Framework Core XBullet.EasyTesting.EntityFrameworkCore
Stub an outbound HTTP API Test outbound HTTP dependencies XBullet.EasyTesting.Http
Record messages published by the application Test published messages XBullet.EasyTesting.Messaging
Assert logs, traces, or metrics Test logs, traces, metrics, and time XBullet.EasyTesting.Observability
Test Azure SDK clients without a live service Test Azure SDK clients XBullet.EasyTesting.Azure
Run real infrastructure for a scenario Test with containerized infrastructure XBullet.EasyTesting.Testcontainers
Test an Aspire distributed application Test an Aspire distributed application XBullet.EasyTesting.Aspire
Test .NET isolated Azure Functions Test .NET isolated Azure Functions XBullet.EasyTesting.AzureFunctions
Assert JSON, text, controller responses, or exchanges Create and review a snapshot XBullet.EasyTesting.Snapshots.Core
Snapshot outbound requests captured by HTTP stubs Outbound HTTP snapshot recipe XBullet.EasyTesting.Snapshots.Http
Choose built-in snapshots or Verify.Xunit Compare snapshot engines Core or XBullet.EasyTesting.Verify.Xunit
Keep credentials and personal data out of artifacts Protect sensitive test data All packages
Run tests safely across frameworks and in parallel Design multi-target and parallel tests All packages

Choose packages

Install only the packages required by the test project.

For core behavior, see test-host selection, authentication models, scenarios and isolation, resources and cleanup, sensitive-data safety, and multi-target and parallel execution.

Application host and persistence

Package Use it when... Usually combined with
XBullet.EasyTesting You need an in-memory ASP.NET Core host, test identities, scenario isolation, or response assertions Any extension package
XBullet.EasyTesting.EntityFrameworkCore A scenario must seed, query, recreate, or clean up an EF Core database Core package and optionally Testcontainers

Application boundaries and diagnostics

Package Use it when... Usually combined with
XBullet.EasyTesting.Http The application calls an external HTTP service that the test should stub and inspect Core package; optionally snapshot HTTP adapters
XBullet.EasyTesting.Messaging The application publishes messages whose transport, destination, headers, or payload must be asserted Core package
XBullet.EasyTesting.Observability A test must assert structured logs, distributed traces, metrics, or deterministic time Core package
XBullet.EasyTesting.Azure Code uses Azure SDK clients and needs deterministic responses, paging, credentials, or pipeline transport Core package when used in hosted scenarios

Runtime environments

Package Use it when... Runtime prerequisite
XBullet.EasyTesting.Testcontainers A test needs a real PostgreSQL, SQL Server, Kafka, Redis, RabbitMQ, Azurite, Service Bus emulator, or custom container; see the infrastructure guide Docker-compatible container runtime
XBullet.EasyTesting.Aspire A closed-box test must start an Aspire application, discover resources, wait for readiness, and collect diagnostics; see the Aspire guide An Aspire app host
XBullet.EasyTesting.AzureFunctions A test directly invokes .NET isolated functions or constructs trigger, binding, middleware, retry, or Durable activity state; see the Functions guide .NET isolated worker application

Snapshot assertions

Package Use it when... Important boundary
XBullet.EasyTesting.Snapshots.Core You want framework-independent JSON, text, controller-response, or complete HTTP-exchange snapshots; see the workflow hub Does not contain adapters for XBullet.EasyTesting.Http stubs
XBullet.EasyTesting.Snapshots.Http You want snapshots of requests and exchanges recorded by StubHttpMessageHandler; see the recipe Requires the HTTP package and snapshot core
XBullet.EasyTesting.Snapshots Existing code needs the compatibility facade over both snapshot packages; see the migration guide Prefer the specific core and HTTP packages for new projects
XBullet.EasyTesting.Verify.Xunit A test suite uses Verify.Xunit v3 and needs controller-response integration; see the engine comparison Uses Verify's approval workflow rather than the built-in snapshot engine

The built-in and Verify snapshot integrations can coexist. When a test suite uses both, document which workflow owns each snapshot so file naming, review, and acceptance remain predictable.

Important testing boundaries

  • Simulated test users validate authorization behavior, not production credential validation. Use the end-to-end authentication path when token, certificate, or API-key parsing is part of the behavior under test.
  • The EF Core in-memory provider does not reproduce relational constraints or transactions. Use SQLite or the production provider when those behaviors matter.
  • Testcontainers requires a Docker-compatible runtime. Service Bus emulator scenarios also require explicit license acceptance.
  • Durable Functions support is intentionally focused on CallActivityAsync; timers, external events, sub-orchestrators, and replay behavior require another testing layer.
  • Snapshot and diagnostic output can contain sensitive application data. Configure exclusions or redaction before committing files or publishing logs; follow the sensitive-data safety model.
  • Multi-target and parallel test runs need explicit ownership for databases, recorders, collectors, files, ports, and infrastructure. See multi-target and parallel execution.

See the maintained limitations register for the full baseline and the package guides for feature-specific constraints.

Examples and source

The repository currently uses integration tests as the primary executable examples:

Canonical documentation examples use named source regions and are synchronized into Markdown by eng/sync-documentation-snippets.ps1. See how to add executable documentation examples.

Contribute to the documentation

Follow the documentation style guide and start a new task-oriented page from the feature-guide template. The coverage baseline records current gaps and target milestones. See the maintenance policy for automated checks and review cadence, and use the release checklist before tagging packages.

Edit this page