Installation (xUnit)

Install the package

dotnet add package ExecutableStories.Xunit

Requires .NET 8.0 or later and C# 12 or later.

Test class setup

The Story class uses static methods. Because xUnit creates a new test class instance per test, you must call Story.RecordAndClear() at the end of each test (or in Dispose) to flush the scenario before the next one starts.

The recommended pattern is to implement IDisposable on your test class:

using ExecutableStories;
using Xunit;

public class LoginTests : IDisposable
{
    public void Dispose()
    {
        Story.RecordAndClear();
    }

    [Fact]
    public void UserLogsInSuccessfully()
    {
        Story.Init("user logs in successfully");

        Story.Given("the user is on the login page");
        // ... test logic ...
        Story.When("the user submits valid credentials");
        // ... assertions ...
        Story.Then("the user should see the dashboard");
    }
}

If you do not call Story.RecordAndClear(), data from one test will bleed into the next.

Default output

The raw run JSON is written to .executable-stories/raw-run.json when the test process exits. The file is written relative to the working directory, which is typically the test project root.

Generate a report

Pass the raw run JSON to executable-stories-formatters to render Markdown, HTML, JUnit XML, or Cucumber formats:

npx executable-stories-formatters format --input .executable-stories/raw-run.json --format markdown

Install the formatters package once in your Node project or CI job:

npm install -D executable-stories-formatters

Next

First Story (xUnit) — write your first C# scenario.

xUnit story & doc API — steps, docs, and adapter options.