Tabular Attributes

Tabular Attributes

Added in v2.32.0

Tabular attributes let you define data-driven tests with typed input and output rows directly on your test methods — no extra data classes, no CSV files, no ceremony. Column names are declared inline, rows are positionally aligned, and output verification is built in.

---

Quick Start (xUnit v3)

using TestTrackingDiagrams.TabularAttributes;

public class GreetingTests
{
    [Theory]
    [HeadIn("Name",  "Age"), HeadOut("Message")]
    [Inputs("Alice", 30),    Outputs("Hello Alice")]
    [Inputs("Bob",   25),    Outputs("Hello Bob")]
    public void Greeting_matches_name(
        TabularInputs<Person> inputs, TabularOutputs<Greeting> outputs)
    {
        foreach (var person in inputs)
        {
            var result = Greet(person);
            outputs.AddActual(result);
        }
        outputs.Verify();
    }

    private Greeting Greet(Person p) => new() { Message = $"Hello {p.Name}" };
}

public class Person
{
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

public class Greeting
{
    public string Message { get; set; } = "";
}

How it works

1. [HeadIn("Name", "Age")] declares the input column names and acts as the data source (replaces [InlineData]/[MemberData]).
2. [HeadOut("Message")] declares the output column names.
3. [Inputs("Alice", 30)] defines one row of input data. Add as many as you need.
4. [Outputs("Hello Alice")] defines the corresponding expected output row.
5. TabularInputs<Person> is an IReadOnlyList<Person> — iterate with foreach to get per-row diagram delimiters.
6. TabularOutputs<Greeting> collects actual results via AddActual() and verifies them against expected rows via Verify().

---

Attributes

Core Attributes (in TestTrackingDiagrams package)

Attribute	Target	AllowMultiple	Purpose
[Inputs(...)]	Method	Yes	One row of input values (positional, matching [HeadIn] columns)
[Outputs(...)]	Method	Yes	One row of expected output values (positional, matching [HeadOut] columns)
[HeadOut(...)]	Method	No	Declares output column names

Framework-Specific [HeadIn] (separate packages)

Framework	Package	Base Type
xUnit v3	TestTrackingDiagrams.xUnit3	Xunit.v3.DataAttribute
xUnit v2	TestTrackingDiagrams.xUnit2	Xunit.Sdk.DataAttribute
NUnit 4	TestTrackingDiagrams.NUnit4	NUnitAttribute, ITestBuilder
MSTest	TestTrackingDiagrams.MSTest	Attribute, ITestDataSource

All [HeadIn] attributes live in namespace TestTrackingDiagrams.TabularAttributes, so a single using covers everything.

---

Data Types

TabularInputs<T>

IReadOnlyList<T> containing deserialized input rows. Iterating with foreach automatically emits per-row diagram delimiters (hnote annotations that visually separate each row's interactions in the sequence diagram).

// Access by index
var first = inputs[0];

// Iterate (emits diagram delimiters)
foreach (var person in inputs)
{
    await sut.Process(person);
}

TabularOutputs<T>

IReadOnlyList<T> containing expected output rows. After processing, call AddActual() for each actual result and then Verify() to compare.

// Record actual output
outputs.AddActual(result);

// Verify all rows (position-based matching)
outputs.Verify(); // throws TabularVerificationException on mismatch

Verification rules:

• Matching rows: expected and actual at the same position are compared cell by cell.
• Surplus rows: more actuals than expected → fail.
• Missing rows: fewer actuals than expected → fail.

---

Column-to-Property Matching

Column names are matched to T's public properties using a sanitization process:

Column Name	Matches Property
"Name"	Name
"First Name"	FirstName (spaces removed)
"Name & Age"	NameAndAge (& → And)
"username"	USERNAME (case-insensitive)

If [HeadIn] is used without arguments ([HeadIn]), column names are inferred from T's public property names.

---

Framework Usage

xUnit v3

[Theory]
[HeadIn("Name", "Age")]
[Inputs("Alice", 30)]
public void My_test(TabularInputs<Person> inputs) { ... }

xUnit v2

[Theory]
[HeadIn("Name", "Age")]
[Inputs("Alice", 30)]
public void My_test(TabularInputs<Person> inputs) { ... }

NUnit 4

[Test]
[HeadIn("Name", "Age")]
[Inputs("Alice", 30)]
public void My_test(TabularInputs<Person> inputs) { ... }

MSTest

[TestMethod]
[HeadIn("Name", "Age")]
[Inputs("Alice", 30)]
public void My_test(TabularInputs<Person> inputs) { ... }

---

Step Tracking Integration

When TabularInputs<T> or TabularOutputs<T> is passed as a step parameter, StepCollector automatically detects it and renders it as a tabular parameter in the report (instead of inline text):

Track.That.Given("the test data", "inputs", inputs);

This produces a table in the step parameters showing all rows and columns.

---

Inputs Only (No Outputs)

You can use TabularInputs<T> without outputs:

[Theory]
[HeadIn("Name", "Age")]
[Inputs("Alice", 30)]
[Inputs("Bob",   25)]
public void Process_people(TabularInputs<Person> inputs)
{
    foreach (var person in inputs)
    {
        sut.Process(person);
    }
}

Outputs Only (No Inputs)

You can also use only TabularOutputs<T>:

[Theory]
[HeadIn, HeadOut("Name", "Status")]
[Outputs("Alice", "Active")]
[Outputs("Bob",   "Inactive")]
public void Verify_results(TabularOutputs<UserStatus> outputs)
{
    outputs.AddActual(new UserStatus { Name = "Alice", Status = "Active" });
    outputs.AddActual(new UserStatus { Name = "Bob", Status = "Inactive" });
    outputs.Verify();
}

---

Performance Considerations

Tabular attributes batch multiple data rows into a single test execution. This is useful when:

• You want to verify a batch operation processes all rows correctly.
• You want per-row diagram delimiters showing each row's interactions.
• You want to compare expected vs actual outputs positionally.

For truly independent test cases (where each row should be a separate test run with its own pass/fail), use the framework's native parameterisation ([InlineData], [TestCase], etc.) instead.

---

Related

• Step Tracking — BDD-style step methods
• Generated Reports — how tabular parameters appear in reports
• Assertion Tracking — tracking assertion pass/fail