# RunAssertions

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.testing.runassertions/
> Summary: RunAssertions: Assertions on a recorded run.

<div class="api-provenance">Namespace Tracon.Testing · Assembly <code>Tracon.Testing.dll</code></div>

Assertions on a recorded run.

```csharp
public sealed class RunAssertions
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.testing.runassertions/">RunAssertions</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

Each unmet assertion throws [TraconAssertionException](/api/tracon.testing.traconassertionexception/) and
writes the **expected and actual** value in its message. Streaming runs are
covered too: `run_events` fills in on the streaming path as well, no
separate type is needed.

## Properties

### <a id="Tracon_Testing_RunAssertions_Events"></a> Events

The run's event stream, in sequence order.

```csharp
public IReadOnlyList<RunEvent> Events { get; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RunEvent](/api/tracon.runevent/)\>

### <a id="Tracon_Testing_RunAssertions_Record"></a> Record

The run record.

```csharp
public RunRecord Record { get; }
```

#### Property Value

 [RunRecord](/api/tracon.runrecord/)

### <a id="Tracon_Testing_RunAssertions_ToolInvocations"></a> ToolInvocations

Tool calls made during the run.

```csharp
public IReadOnlyList<ToolInvocationRecord> ToolInvocations { get; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[ToolInvocationRecord](/api/tracon.toolinvocationrecord/)\>

## Methods

### <a id="Tracon_Testing_RunAssertions_ShouldHaveCalledTool_System_String_System_Nullable_System_Int32__"></a> ShouldHaveCalledTool\(string, int?\)

Asserts that a specific tool was called.

```csharp
public RunAssertions ShouldHaveCalledTool(string toolName, int? times = null)
```

#### Parameters

`toolName` [string](https://learn.microsoft.com/dotnet/api/system.string)

Tool name.

`times` [int](https://learn.microsoft.com/dotnet/api/system.int32)?

If given, the exact number of calls expected.

#### Returns

 [RunAssertions](/api/tracon.testing.runassertions/)

The chain, for continued assertions.

#### Exceptions

 [TraconAssertionException](/api/tracon.testing.traconassertionexception/)

The tool was never called, or the count does not match.

### <a id="Tracon_Testing_RunAssertions_ShouldHaveCompleted"></a> ShouldHaveCompleted\(\)

Asserts that the run completed successfully.

```csharp
public RunAssertions ShouldHaveCompleted()
```

#### Returns

 [RunAssertions](/api/tracon.testing.runassertions/)

The chain, for continued assertions.

#### Exceptions

 [TraconAssertionException](/api/tracon.testing.traconassertionexception/)

The status is not [RunStatus.Completed](/api/tracon.runstatus/).

### <a id="Tracon_Testing_RunAssertions_ShouldHaveFailed"></a> ShouldHaveFailed\(\)

Asserts that the run ended with a failure.

```csharp
public RunAssertions ShouldHaveFailed()
```

#### Returns

 [RunAssertions](/api/tracon.testing.runassertions/)

The chain, for continued assertions.

#### Exceptions

 [TraconAssertionException](/api/tracon.testing.traconassertionexception/)

The status is not [RunStatus.Failed](/api/tracon.runstatus/).

### <a id="Tracon_Testing_RunAssertions_ShouldHaveFailedWith_System_String_"></a> ShouldHaveFailedWith\(string\)

Asserts that the run ended with a specific error type.

```csharp
public RunAssertions ShouldHaveFailedWith(string errorType)
```

#### Parameters

`errorType` [string](https://learn.microsoft.com/dotnet/api/system.string)

The value expected to match [TraconException.ErrorType](/api/tracon.traconexception/#Tracon_TraconException_ErrorType).

#### Returns

 [RunAssertions](/api/tracon.testing.runassertions/)

The chain, for continued assertions.

#### Exceptions

 [TraconAssertionException](/api/tracon.testing.traconassertionexception/)

The status is not [RunStatus.Failed](/api/tracon.runstatus/), or the error type does not match.

### <a id="Tracon_Testing_RunAssertions_ShouldHaveOutputContaining_System_String_"></a> ShouldHaveOutputContaining\(string\)

Asserts that the run's generated text contains a specific substring.

```csharp
public RunAssertions ShouldHaveOutputContaining(string text)
```

#### Parameters

`text` [string](https://learn.microsoft.com/dotnet/api/system.string)

Substring to look for.

#### Returns

 [RunAssertions](/api/tracon.testing.runassertions/)

The chain, for continued assertions.

#### Remarks

If a [RunEventType.MessageCompleted](/api/tracon.runeventtype/) exists (non-streaming
run) it is used; otherwise (a streaming run, e.g. the HTTP `/run`
endpoint) the [RunEventType.MessageDelta](/api/tracon.runeventtype/) chunks are
concatenated. The two are never both present in the same run — also
summing the chunks on the non-streaming path would DUPLICATE the text.

#### Exceptions

 [TraconAssertionException](/api/tracon.testing.traconassertionexception/)

The substring was not found.

### <a id="Tracon_Testing_RunAssertions_ShouldNotHaveCalledTool_System_String_"></a> ShouldNotHaveCalledTool\(string\)

Asserts that a specific tool was never called.

```csharp
public RunAssertions ShouldNotHaveCalledTool(string toolName)
```

#### Parameters

`toolName` [string](https://learn.microsoft.com/dotnet/api/system.string)

Tool name.

#### Returns

 [RunAssertions](/api/tracon.testing.runassertions/)

The chain, for continued assertions.

#### Exceptions

 [TraconAssertionException](/api/tracon.testing.traconassertionexception/)

The tool was called at least once.