Skip to main content

Getting Started

In this guide you'll install the LiveDoc xUnit package, write your first BDD test with Given / When / Then steps, and see beautifully formatted test output — all in about five minutes.

What You'll Build​

By the end of this page you will have:

  • A working .NET + xUnit test project with LiveDoc installed
  • A test class using Gherkin-style syntax (Given / When / Then)
  • Structured test output that doubles as living documentation

Prerequisites​

  • .NET 8 SDK (or later) installed
  • A terminal and a code editor (Visual Studio or VS Code recommended)
  • Basic familiarity with C# and xUnit

Step 1: Create a Test Project​

If you already have an xUnit test project, skip to Step 2.

mkdir MyProject.Tests && cd MyProject.Tests
dotnet new xunit

This scaffolds a standard xUnit project with a single test file.

Step 2: Install LiveDoc​

dotnet add package SweDevTools.LiveDoc.xUnit

That's it — one package, no extra configuration files.

Already using xUnit?

LiveDoc builds on top of xUnit's existing infrastructure. [Scenario] inherits from [Fact] and [ScenarioOutline] inherits from [Theory], so your test runner, IDE integrations, and CI pipelines all work unchanged.

Step 3: Write Your First Test​

Replace the generated UnitTest1.cs with a file called CalculatorTests.cs:

using SweDevTools.LiveDoc.xUnit;
using Xunit;
using Xunit.Abstractions;

namespace MyProject.Tests;

[Feature("Calculator")]
public class CalculatorTests : FeatureTest
{
    public CalculatorTests(ITestOutputHelper output) : base(output)
    {
    }

    [Scenario("Adding two numbers")]
    public void Adding_two_numbers()
    {
        int result = 0;

        Given("I have entered '50' into the calculator", () =>
        {
            result = 50;
        });

        And("I have entered '70' into the calculator", () =>
        {
            result += 70;
        });

        When("I press equals", () =>
        {
            // calculation already happened above
        });

        Then("the result should be '120'", () =>
        {
            Assert.Equal(120, result);
        });
    }
}

Things to Notice​

PatternWhy
FeatureTest base classProvides the Given(), When(), Then(), And(), But() step methods.
[Feature("...")]Marks the class as a BDD feature — the title appears in formatted output.
[Scenario("...")]Marks a test method as a scenario. Inherits [Fact], so xUnit discovers it automatically.
ITestOutputHelperStandard xUnit mechanism for capturing test output. Required by the constructor.
Quoted values '50'Values in step titles make tests self-documenting. See Value Extraction.
The constructor pattern

Every LiveDoc test class must accept ITestOutputHelper output in its constructor and pass it to base(output). This is how LiveDoc captures and formats the test output that appears in your IDE and test reports.

Step 4: Run It 🎉​

dotnet test

You'll see output like this in the test detail panel:

Feature: Calculator

  Scenario: Adding two numbers
    Given I have entered '50' into the calculator
      And I have entered '70' into the calculator
    When I press equals
    Then the result should be '120'

    ✓ 4 passing (12ms)

Every step title appears in the output — that's living documentation. When the business rules change, the tests and their output change with them.

Step 5: Add a Second Scenario​

Let's add another scenario to see how features group multiple tests:

[Scenario("Subtracting two numbers")]
public void Subtracting_two_numbers()
{
    int result = 0;

    Given("I have entered '100' into the calculator", () =>
    {
        result = 100;
    });

    When("I subtract '37'", () =>
    {
        result -= 37;
    });

    Then("the result should be '63'", () =>
    {
        Assert.Equal(63, result);
    });
}

Run dotnet test again — both scenarios appear under the same feature heading:

Feature: Calculator

  Scenario: Adding two numbers
    Given I have entered '50' into the calculator
      And I have entered '70' into the calculator
    When I press equals
    Then the result should be '120'

    ✓ 4 passing (12ms)

  Scenario: Subtracting two numbers
    Given I have entered '100' into the calculator
    When I subtract '37'
    Then the result should be '63'

    ✓ 3 passing (6ms)

Step 6: See It in Your IDE​

Visual Studio Test Explorer​

Tests appear as regular xUnit tests:

📁 CalculatorTests
  ✅ Adding_two_numbers

Click a test to see the formatted BDD output in the Test Detail Summary panel.

VS Code​

Install the .NET Test Explorer extension and run tests directly from the editor. Output appears in the terminal panel.

Namespace Matters​

Your C# namespace determines how tests are grouped in the LiveDoc Viewer. Organize namespaces by feature area for a clean report hierarchy:

MyProject.Tests/
├── Checkout/           → "Checkout" in the viewer tree
│   └── CartTests.cs
├── Shipping/           → "Shipping" in the viewer tree
│   └── CostsTests.cs
└── Auth/               → "Auth" in the viewer tree
    └── LoginTests.cs
caution

Avoid flat namespaces — placing all tests in a single namespace produces a flat, hard-to-navigate list in the viewer.

Recap​

  • Install SweDevTools.LiveDoc.xUnit via NuGet
  • Inherit from FeatureTest and add [Feature] to the class
  • Mark tests with [Scenario] — it inherits from [Fact]
  • Write steps with Given() / When() / Then() / And() / But()
  • Constructor must accept ITestOutputHelper and pass it to base(output)
  • Run with dotnet test and enjoy structured, readable output

Next Steps​