Written by Sujith Quintelier • Oct 29, 2025

Mastering Asynchronous Programming with C# async/await - Part 7: Testing & Debugging

Testing & debugging async: proper async unit tests, mocking, handling aggregated exceptions, tooling (tasks window, async stacks), and tracing flows.

Oct 29, 2025

Part 7: Testing and Debugging Async Code

You’ve learned how to write async code — but how do you test it and debug it when things go wrong? Async introduces unique challenges: hidden continuations, exceptions in background tasks, and “lost” operations. Let’s tackle them.

Writing Async Unit Tests

Most modern test frameworks (xUnit, NUnit, MSTest) fully support async tests.

✅ Correct:

[Fact] // xUnit
public async Task GetNumberAsync_Returns42()
{
    var result = await GetNumberAsync();
    Assert.Equal(42, result);
}

⚠️ Avoid this (blocks async code and may deadlock):

[Fact]
public void BadTest()
{
    var result = GetNumberAsync().Result; // ❌
    Assert.Equal(42, result);
}

Rule: Your test method should return Task if it calls async code.

Mocking Async Methods

When testing async code, you’ll often need to mock dependencies.

Example with Moq:

var mockRepo = new Mock<IUserRepository>();
mockRepo.Setup(r => r.GetUserAsync(It.IsAny<int>()))
        .ReturnsAsync(new User { Id = 1, Name = "Alice" });

var service = new UserService(mockRepo.Object);
var user = await service.GetUserAsync(1);

Assert.Equal("Alice", user.Name);

Here, ReturnsAsync makes it easy to simulate async results.

Testing Multiple Tasks and Exceptions

When using Task.WhenAll, multiple exceptions are aggregated. Test them explicitly:

var t1 = FailsAsync();
var t2 = FailsAsync();

var ex = await Assert.ThrowsAsync<AggregateException>(async () => await Task.WhenAll(t1, t2));
Assert.Equal(2, ex.InnerExceptions.Count);

Or unwrap with try/catch:

try
{
    await Task.WhenAll(t1, t2);
}
catch (Exception e)
{
    // e is AggregateException in .NET Framework, but flattens to first inner in .NET Core when awaited; check tasks for details
    var errors = new[] { t1.Exception, t2.Exception };
}

Debugging Async Code in Visual Studio

Async stacks can look confusing, but Visual Studio helps:

Tasks Window (Debug > Windows > Parallel Tasks)
Shows all active tasks, their status, and call stacks.
Async Call Stacks (Debug > Options > Enable Just My Code and ensure “Show Async Call Stack”)
Preserves the logical async flow across awaits.
Configure Breakpoints
Use conditions and actions to break when a specific OperationId or correlation ID is present in logs.

Tracing Async Flows with Logging and `Activity`

Logging is critical to see what’s happening between awaits.

Example with ILogger (ASP.NET Core):

public async Task ProcessAsync(ILogger logger, CancellationToken ct)
{
    logger.LogInformation("Starting work");
    await Task.Delay(1000, ct);
    logger.LogInformation("Work complete");
}

For cross-service tracing, use System.Diagnostics.Activity (and OpenTelemetry if available):

using var activity = new Activity("FetchCustomer")
    .AddTag("customer.id", id.ToString());
activity.Start();

var customer = await repo.GetCustomerAsync(id, ct);

activity.Stop();

With OpenTelemetry exporters (Jaeger, Zipkin, OTLP), you can see async spans stitched together.

Handling Unobserved and Fire‑and‑Forget Exceptions

Async tasks can fail silently if you forget to await them. .NET raises TaskScheduler.UnobservedTaskException, but it’s often too late and can be GC‑dependent.

✅ Patterns that help:

// 1) Prefer awaiting
await DoWorkAsync();

// 2) If fire-and-forget is necessary, capture errors
_ = Task.Run(async () =>
{
    try
    {
        await DoWorkAsync();
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Background task failed");
    }
});

In libraries, consider returning an IAsyncDisposable that manages background lifetimes so callers can dispose and observe errors on shutdown.

Deterministic Tests with Time and Cancellation

Make tests reliable by controlling time and tokens:

Pass a CancellationToken into your methods and cancel in tests to assert behavior.
Abstract timers/delays behind an interface so you can fake time in tests (e.g., wrap Task.Delay behind ITimer.DelayAsync).

Example fake timer:

public interface ITimer
{
    Task Delay(TimeSpan delay, CancellationToken ct = default);
}

public sealed class RealTimer : ITimer
{
    public Task Delay(TimeSpan delay, CancellationToken ct = default) => Task.Delay(delay, ct);
}

public sealed class FakeTimer : ITimer
{
    public TaskCompletionSource Completed { get; } = new();
    public Task Delay(TimeSpan delay, CancellationToken ct = default) => Completed.Task;
}

Common Testing Smells (and Fixes)

Using .Result/.Wait() in tests → switch to async Task tests.
Races on shared state → isolate state per test or use fixtures with fresh instances.
Flaky tests due to real network/IO → mock or use local test servers/files.
Hidden deadlocks → remove context capture in test targets (ConfigureAwait(false) in libraries).