# BDTest

> BDTest is a code-only behaviour-driven testing and reporting framework for .NET. Write Given/When/Then scenarios in C# with NUnit, xUnit, MSTest or TUnit, and publish readable reports.


## search

- [Search the documentation](https://bdtest.tomlonghurst.dev/search.md)

## docs

BDTest is a code-only behaviour-driven testing and reporting framework for .NET.

- [What is BDTest?](https://bdtest.tomlonghurst.dev/docs.md): BDTest is a code-only behaviour-driven testing and reporting framework for .NET.

### advanced

- [Analyzers and code fixes](https://bdtest.tomlonghurst.dev/docs/advanced/analyzers.md): Catch unexecuted scenarios, invalid step text, incomplete stories and discarded asynchronous work at compile time.
- [Explicit runs](https://bdtest.tomlonghurst.dev/docs/advanced/explicit-runs.md): Isolate scenario storage and reporting with BDTestRun in custom adapters and long-lived hosts.
- [Compiler step metadata](https://bdtest.tomlonghurst.dev/docs/advanced/source-generator.md): The source generator bundled in BDTest that records step call-site metadata at compile time.
- [Utilities and model](https://bdtest.tomlonghurst.dev/docs/advanced/utilities.md): Read collected scenarios with BDTestUtil, and the Scenario, Step and BDTestContext types.

### attributes

- [Story text](https://bdtest.tomlonghurst.dev/docs/attributes/story-text.md): Format story roles, goals, and benefits with StoryAttribute.

### configuration

- [Assembly runs](https://bdtest.tomlonghurst.dev/docs/configuration/assembly-runs.md): Configure, report and dispose isolated runs owned by the built-in adapters.
- [Console output](https://bdtest.tomlonghurst.dev/docs/configuration/console-output.md): Plain-text reporting and output capture during parallel scenarios.
- [Exception classification](https://bdtest.tomlonghurst.dev/docs/configuration/exceptions.md): How BDTest maps exceptions to step and scenario statuses, including inheritance, wrappers and per-run registrations.
- [Retry hook errors](https://bdtest.tomlonghurst.dev/docs/configuration/retry-hook-errors.md): Inspect failures from retry setup, teardown and OnBeforeRetry hooks.
- [Settings](https://bdtest.tomlonghurst.dev/docs/configuration/settings.md): Configure frozen BDTestOptions for an assembly or an explicitly owned run.
- [Statuses](https://bdtest.tomlonghurst.dev/docs/configuration/statuses.md): The Status values for steps and scenarios, how a scenario's status is decided, and how statuses are ranked in reports.

### contributing

Build, test and document BDTest locally.

- [Contributing](https://bdtest.tomlonghurst.dev/docs/contributing.md): Build, test and document BDTest locally.

### frameworks

- [Composition host](https://bdtest.tomlonghurst.dev/docs/frameworks/composition.md): Use context, scenarios, and output helpers without inheriting a BDTest base class.
- [Custom adapters](https://bdtest.tomlonghurst.dev/docs/frameworks/custom-adapters.md): Connect BDTest to another test runner with BeginTest and EndTest, exception registrations and skip handling.
- [MSTest](https://bdtest.tomlonghurst.dev/docs/frameworks/mstest.md): Use BDTest with MSTest through composition or MSTestBDTestBase<TContext>.
- [NUnit](https://bdtest.tomlonghurst.dev/docs/frameworks/nunit.md): Use BDTest with NUnit through composition or an optional base class.
- [Choosing a test framework](https://bdtest.tomlonghurst.dev/docs/frameworks/overview.md): Compare the BDTest adapters for TUnit, NUnit, xUnit and MSTest, or run BDTest standalone.
- [Standalone](https://bdtest.tomlonghurst.dev/docs/frameworks/standalone.md): Use BDTest without a framework adapter through BDTestBase and BDTestBuilder.
- [TUnit](https://bdtest.tomlonghurst.dev/docs/frameworks/tunit.md): Use BDTest with TUnit through composition or TUnitBDTestBase<TContext>.
- [xUnit](https://bdtest.tomlonghurst.dev/docs/frameworks/xunit.md): Use BDTest with xUnit v3 through composition or an optional base class.

### getting-started

- [Example project](https://bdtest.tomlonghurst.dev/docs/getting-started/example-project.md): A tour of the BDTest.Example sample project in the repository.
- [Your first test](https://bdtest.tomlonghurst.dev/docs/getting-started/first-test.md): Write, run and report a complete BDTest scenario with TUnit.
- [Installation](https://bdtest.tomlonghurst.dev/docs/getting-started/installation.md): Install BDTest and the adapter for your test framework from NuGet.

### migration

- [Migrating to async-only execution](https://bdtest.tomlonghurst.dev/docs/migration/async-only.md): Replace the removed synchronous BDTest() entry points with awaited BDTestAsync() calls.
- [Consumer namespaces](https://bdtest.tomlonghurst.dev/docs/migration/consumer-namespaces.md): Use one BDTest namespace for test bases, fluent builders and attributes.
- [Migrating to delegate steps](https://bdtest.tomlonghurst.dev/docs/migration/delegate-steps.md): Step builders now take delegates instead of expression trees. What changes for helpers, step text and arguments.
- [Explicit run ownership](https://bdtest.tomlonghurst.dev/docs/migration/explicit-runs.md): Migrate global settings, hooks, builders and report helpers to owned runs.
- [Public names and fluent builders](https://bdtest.tomlonghurst.dev/docs/migration/fluent-builders.md): Migrate report identity properties, parameter names, builder variables and inline contexts.
- [Coming from SpecFlow](https://bdtest.tomlonghurst.dev/docs/migration/from-specflow.md): Map SpecFlow and Gherkin concepts to BDTest code.
- [Generated name text changes](https://bdtest.tomlonghurst.dev/docs/migration/generated-name-text.md): Release notes for replacing Humanizer.Core with BDTest's internal method name splitter in the next major version.
- [Immutable results and versioned JSON](https://bdtest.tomlonghurst.dev/docs/migration/immutable-results.md): Migrate execution results, hooks and report consumers to BDTest.Contracts.
- [Migrating away from implementation helpers](https://bdtest.tomlonghurst.dev/docs/migration/internal-helpers.md): Supported replacements for helpers removed from the next major public API.
- [JSON serialization changes](https://bdtest.tomlonghurst.dev/docs/migration/json-serialization.md): BDTest moved from Newtonsoft.Json to source-generated System.Text.Json. What changes for report readers, data stores and report hosts.
- [Named step text](https://bdtest.tomlonghurst.dev/docs/migration/named-step-text.md): Migrate positional StepText placeholders and display overrides to parameter names.
- [Upgrading to the next major version](https://bdtest.tomlonghurst.dev/docs/migration/next-major.md): Start here when migrating existing BDTest tests, adapters and report hosts.
- [Report options and dependency injection](https://bdtest.tomlonghurst.dev/docs/migration/report-options.md): Move report host configuration from middleware to validated options and DI registrations.
- [Report storage interfaces](https://bdtest.tomlonghurst.dev/docs/migration/report-storage.md): Move custom report storage to cancellable streams and a paged index.
- [Reporting package](https://bdtest.tomlonghurst.dev/docs/migration/reporting-package.md): Add BDTest.Reporting for execution-side report export and upload in the next major version.
- [Scenario definitions](https://bdtest.tomlonghurst.dev/docs/migration/scenario-definitions.md): Migrate pending-report consumers from fluent builders to definition summaries.
- [Status changes](https://bdtest.tomlonghurst.dev/docs/migration/statuses.md): The NotRun and Pending statuses, the new meaning of Inconclusive, and changed numeric enum values.
- [Structured exceptions](https://bdtest.tomlonghurst.dev/docs/migration/structured-exceptions.md): Full exception identities, nested diagnostics and root-cause grouping in BDTest reports.
- [Target framework migration](https://bdtest.tomlonghurst.dev/docs/migration/target-frameworks.md): Native .NET 8 runtime assets, retained .NET Standard support, nullable contracts, and private compiler polyfills.

### report-server

- [Caching and limits](https://bdtest.tomlonghurst.dev/docs/report-server/caching-and-limits.md): The report server's bounded full-report cache, retention, upload size limits and bulk comparison limits.
- [Customizing the report server](https://bdtest.tomlonghurst.dev/docs/report-server/customization.md): Add team and run links, personalise the page for the signed-in user, and react to uploaded reports.
- [Hosting](https://bdtest.tomlonghurst.dev/docs/report-server/hosting.md): Deploy the report server, and run it behind a reverse proxy or under a path prefix.
- [Report server overview](https://bdtest.tomlonghurst.dev/docs/report-server/overview.md): What the BDTest report server does and how its pieces fit together.
- [Persistent storage](https://bdtest.tomlonghurst.dev/docs/report-server/persistence.md): Implement cancellable report byte storage and a paged run index.
- [Sample server](https://bdtest.tomlonghurst.dev/docs/report-server/sample-server.md): Run and deploy BDTest.ReportGenerator.RazorServer, the sample report host with Azure Blob Storage and Microsoft Entra ID.
- [Securing the report server](https://bdtest.tomlonghurst.dev/docs/report-server/security.md): Protect report pages with authentication, protect uploads with an API key, and control who can delete reports.
- [Sending results](https://bdtest.tomlonghurst.dev/docs/report-server/sending-results.md): Upload test results to a BDTest report server at the end of a test run.
- [Setting up a report server](https://bdtest.tomlonghurst.dev/docs/report-server/setup.md): Register BDTest report services, bind validated options, and add the report middleware.

### reports

- [CI integration](https://bdtest.tomlonghurst.dev/docs/reports/ci-integration.md): Publish BDTest HTML reports from GitHub Actions and Azure DevOps, and upload results to a report server.
- [Versioned report contracts](https://bdtest.tomlonghurst.dev/docs/reports/contracts.md): Immutable report DTOs in BDTest.Contracts, independent of execution.
- [HTML report](https://bdtest.tomlonghurst.dev/docs/reports/html-report.md): Generate a single self-contained HTML report with BDTestHtmlHelper.
- [HTML report security](https://bdtest.tomlonghurst.dev/docs/reports/html-report-security.md): Custom HTML isolation and Content Security Policy in standalone reports.
- [JSON data](https://bdtest.tomlonghurst.dev/docs/reports/json-data.md): Export, read and write BDTest report data as JSON with BDTestJsonHelper.
- [Reports overview](https://bdtest.tomlonghurst.dev/docs/reports/overview.md): The ways to get results out of BDTest - console output, a self-contained HTML file, JSON data and the report server.
- [Shared HTML renderer](https://bdtest.tomlonghurst.dev/docs/reports/rendering.md): Render immutable reports without test execution and share run and scenario sections with hosted reports.

### writing-tests

- [Asynchronous steps](https://bdtest.tomlonghurst.dev/docs/writing-tests/async-steps.md): Use async steps, await scenarios, and understand how BDTest treats synchronization contexts.
- [Attachments](https://bdtest.tomlonghurst.dev/docs/writing-tests/attachments.md): Capture screenshots, logs and files with run-owned temporary storage and step association.
- [Output and custom HTML](https://bdtest.tomlonghurst.dev/docs/writing-tests/output.md): How BDTest captures console output, records setup and teardown output, and lets tests add links, images and HTML to reports.
- [Retries](https://bdtest.tomlonghurst.dev/docs/writing-tests/retries.md): Retry failing scenarios with [BDTestRetry] or run retry rules, and reset state between attempts.
- [Scenario hooks](https://bdtest.tomlonghurst.dev/docs/writing-tests/scenario-hooks.md): Run setup and cleanup for each scenario attempt with typed context, outcome and cancellation access.
- [Scenario outlines](https://bdtest.tomlonghurst.dev/docs/writing-tests/scenario-outlines.md): Run one scenario over a table of typed example rows.
- [Scenarios and steps](https://bdtest.tomlonghurst.dev/docs/writing-tests/scenarios.md): Build Given / When / Then chains, the rules for which steps can follow which, and how a scenario executes.
- [Skipping steps and scenarios](https://bdtest.tomlonghurst.dev/docs/writing-tests/skipping.md): Skip individual steps with SkipStepAttribute rules, skip whole scenarios with global rules, and understand how skips are reported.
- [Step classes](https://bdtest.tomlonghurst.dev/docs/writing-tests/step-classes.md): Organise steps into reusable classes that operate on the test context.
- [Step hooks](https://bdtest.tomlonghurst.dev/docs/writing-tests/step-hooks.md): Run code before and after every step, per run or per test class, for logging, screenshots and diagnostics.
- [Step text](https://bdtest.tomlonghurst.dev/docs/writing-tests/step-text.md): Control how steps read in reports with the source generator, [StepText], WithArgs, WithStepText, argument formatting and custom converters.
- [Stories and scenarios](https://bdtest.tomlonghurst.dev/docs/writing-tests/stories-and-scenarios.md): Describe why a group of tests exists with [Story] and what each test does with [ScenarioText].
- [Tags and test information](https://bdtest.tomlonghurst.dev/docs/writing-tests/tags-and-information.md): Tag scenarios for filtering with [BDTestTag] and attach extra details with [TestInformation].
- [Test context](https://bdtest.tomlonghurst.dev/docs/writing-tests/test-context.md): Create, initialize and dispose per-test state with factories and dependency injection.
- [Timeouts and cancellation](https://bdtest.tomlonghurst.dev/docs/writing-tests/timeouts.md): Cancel scenario execution and bound steps, hooks and scenario attempts.