# Testing & Debugging Workflows
Testing and debugging workflows is crucial for building reliable, production-ready workflow systems. This guide covers comprehensive strategies for testing workflows with xUnit and Elsa.Testing, integration testing patterns, debugging techniques, and best practices for workflow testing in Elsa V3.
## Why Test Workflows?
Workflows often contain critical business logic that needs to be reliable and maintainable. Testing workflows provides:
* **Confidence**: Ensure workflows behave correctly before deployment
* **Regression Prevention**: Catch breaking changes early
* **Documentation**: Tests serve as executable documentation
* **Refactoring Safety**: Make changes without fear of breaking functionality
* **Quality Assurance**: Validate business rules and edge cases
## Unit Testing Workflows
Unit testing workflows involves testing individual workflows or activities in isolation. Elsa provides the `Elsa.Testing` package to make this process straightforward.
### Setting Up Your Test Project
{% stepper %}
{% step %}
**Create Test Project**
Create a new xUnit test project and add the necessary packages:
```bash
dotnet new xunit -n "MyWorkflows.Tests"
cd MyWorkflows.Tests
dotnet add package Elsa
dotnet add package Elsa.Testing.Shared
dotnet add package Microsoft.Extensions.DependencyInjection
dotnet add package xunit
dotnet add package xunit.runner.visualstudio
```
{% endstep %}
{% step %}
**Configure Test Infrastructure**
Create a base test class to set up the Elsa service container:
{% code title="WorkflowTestBase.cs" %}
```csharp
using Elsa.Extensions;
using Elsa.Testing.Shared;
using Elsa.Workflows.Contracts;
using Microsoft.Extensions.DependencyInjection;
using Xunit;
namespace MyWorkflows.Tests;
public abstract class WorkflowTestBase : IAsyncLifetime
{
protected IServiceProvider Services { get; private set; } = default!;
public virtual async Task InitializeAsync()
{
var services = new ServiceCollection();
// Add Elsa services
services.AddElsa();
// Add custom activities or services
ConfigureServices(services);
// Build the service provider
Services = services.BuildServiceProvider();
// Populate registries (required for non-hosted scenarios)
await Services.PopulateRegistriesAsync();
}
protected virtual void ConfigureServices(IServiceCollection services)
{
// Override in derived classes to add custom services
}
public virtual Task DisposeAsync()
{
if (Services is IDisposable disposable)
disposable.Dispose();
return Task.CompletedTask;
}
protected async Task RunWorkflowAsync(Workflow workflow, IDictionary? input = null, CancellationToken cancellationToken = default)
{
var workflowRunner = Services.GetRequiredService();
var result = await workflowRunner.RunAsync(workflow, input, cancellationToken);
return result;
}
}
```
{% endcode %}
{% endstep %}
{% endstepper %}
### Testing a Simple Workflow
Here's an example of testing a workflow that validates and processes user input:
{% code title="UserValidationWorkflowTests.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Activities;
using Elsa.Workflows.Contracts;
using Elsa.Workflows.Models;
using FluentAssertions;
using Xunit;
namespace MyWorkflows.Tests;
public class UserValidationWorkflowTests : WorkflowTestBase
{
[Fact]
public async Task ValidUser_ShouldCompleteSuccessfully()
{
// Arrange
var workflow = new Workflow
{
Root = new Sequence
{
Activities =
{
new SetVariable
{
Variable = new Variable("Email"),
Value = new Input("user@example.com")
},
new If
{
Condition = new Input(context =>
{
var email = context.GetVariable("Email");
return !string.IsNullOrEmpty(email) && email.Contains("@");
}),
Then = new WriteLine
{
Text = new Input("Valid email")
},
Else = new WriteLine
{
Text = new Input("Invalid email")
}
}
}
}
};
// Act
var result = await RunWorkflowAsync(workflow);
// Assert
result.Status.Should().Be(WorkflowStatus.Finished);
result.SubStatus.Should().Be(WorkflowSubStatus.Finished);
}
[Theory]
[InlineData("")]
[InlineData("invalid-email")]
[InlineData("exampledotcom")]
public async Task InvalidEmail_ShouldTakeElseBranch(string email)
{
// Arrange
var executedBranch = "";
var workflow = new Workflow
{
Root = new Sequence
{
Activities =
{
new SetVariable
{
Variable = new Variable("Email"),
Value = new Input(email)
},
new If
{
Condition = new Input(context =>
{
var emailValue = context.GetVariable("Email");
return !string.IsNullOrEmpty(emailValue) && emailValue.Contains("@");
}),
Then = new Inline(context => executedBranch = "Then"),
Else = new Inline(context => executedBranch = "Else")
}
}
}
};
// Act
await RunWorkflowAsync(workflow);
// Assert
executedBranch.Should().Be("Else");
}
}
```
{% endcode %}
### Testing Custom Activities
When testing custom activities, focus on testing the activity's logic in isolation:
{% code title="CustomActivityTests.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Models;
using FluentAssertions;
using Xunit;
namespace MyWorkflows.Tests;
public class CustomActivityTests : WorkflowTestBase
{
[Fact]
public async Task SendEmail_WithValidRecipient_ShouldSucceed()
{
// Arrange
var emailSent = false;
var sendEmailActivity = new SendEmailActivity
{
To = new Input("user@example.com"),
Subject = new Input("Test Subject"),
Body = new Input("Test Body"),
OnEmailSent = () => emailSent = true
};
var workflow = new Workflow
{
Root = sendEmailActivity
};
// Act
var result = await RunWorkflowAsync(workflow);
// Assert
result.Status.Should().Be(WorkflowStatus.Finished);
emailSent.Should().BeTrue();
}
[Fact]
public async Task SendEmail_WithInvalidRecipient_ShouldFail()
{
// Arrange
var sendEmailActivity = new SendEmailActivity
{
To = new Input("invalid-email"),
Subject = new Input("Test Subject"),
Body = new Input("Test Body")
};
var workflow = new Workflow
{
Root = sendEmailActivity
};
// Act
var result = await RunWorkflowAsync(workflow);
// Assert
result.Status.Should().Be(WorkflowStatus.Faulted);
}
}
// Example custom activity for testing
public class SendEmailActivity : CodeActivity
{
public Input To { get; set; } = default!;
public Input Subject { get; set; } = default!;
public Input Body { get; set; } = default!;
public Action? OnEmailSent { get; set; }
protected override void Execute(ActivityExecutionContext context)
{
var to = To.Get(context);
if (string.IsNullOrEmpty(to) || !to.Contains("@"))
{
throw new InvalidOperationException("Invalid email address");
}
// Simulate sending email
OnEmailSent?.Invoke();
}
}
```
{% endcode %}
### Testing Workflow Inputs and Outputs
Test workflows with various input combinations and verify outputs:
{% code title="WorkflowInputOutputTests.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Activities;
using Elsa.Workflows.Contracts;
using Elsa.Workflows.Models;
using FluentAssertions;
using Microsoft.Extensions.DependencyInjection;
using Xunit;
namespace MyWorkflows.Tests;
public class WorkflowInputOutputTests : WorkflowTestBase
{
[Fact]
public async Task Workflow_WithInput_ShouldProduceExpectedOutput()
{
// Arrange
var workflow = new Workflow
{
Root = new Sequence
{
Activities =
{
new SetVariable
{
Variable = new Variable("InputValue"),
Value = new Input(context =>
context.GetInput("value"))
},
new SetVariable
{
Variable = new Variable("Result"),
Value = new Input(context =>
context.GetVariable("InputValue") * 2)
},
new SetOutput
{
OutputName = "Result",
OutputValue = new Input(context =>
context.GetVariable("Result"))
}
}
}
};
var input = new Dictionary
{
["value"] = 5
};
// Act
var result = await RunWorkflowAsync(workflow, input);
// Assert
result.Status.Should().Be(WorkflowStatus.Finished);
var output = result.Output;
output.Should().ContainKey("Result");
output["Result"].Should().Be(10);
}
}
```
{% endcode %}
### Using Elsa's Official Testing Helpers
Elsa provides official testing helper packages that simplify test setup and execution. These are the recommended approaches used in the elsa-core repository.
#### ActivityTestFixture for Unit Testing Activities
The `ActivityTestFixture` from `Elsa.Testing.Shared` package is the recommended way to unit test individual activities:
{% code title="UsingActivityTestFixture.cs" %}
```csharp
using Elsa.Testing.Shared;
using Xunit;
namespace MyWorkflows.Tests;
public class MyActivityUnitTests
{
[Fact]
public async Task MyActivity_Executes_Successfully()
{
// Arrange
var activity = new MyCustomActivity
{
InputProperty = new Input("test value")
};
// Act - ActivityTestFixture handles all setup
var fixture = new ActivityTestFixture(activity);
var context = await fixture.ExecuteAsync();
// Assert - Check activity behavior in isolation
Assert.Equal(ActivityStatus.Completed, context.Status);
}
}
```
{% endcode %}
#### WorkflowTestFixture for Integration Testing
The `WorkflowTestFixture` from `Elsa.Testing.Shared.Integration` provides a complete test infrastructure with proper service setup:
{% code title="UsingWorkflowTestFixture.cs" %}
```csharp
using Elsa.Testing.Shared.Integration;
using Xunit;
using Xunit.Abstractions;
namespace MyWorkflows.Tests.Integration;
public class MyActivityIntegrationTests
{
private readonly WorkflowTestFixture _fixture;
public MyActivityIntegrationTests(ITestOutputHelper testOutputHelper)
{
_fixture = new WorkflowTestFixture(testOutputHelper);
}
[Fact]
public async Task Activity_Completes_Successfully()
{
// Arrange
var activity = new MyActivity { Input = new("test") };
// Act - Runs activity in a complete workflow context
var result = await _fixture.RunActivityAsync(activity);
// Assert
Assert.Equal(WorkflowStatus.Finished, result.WorkflowState.Status);
// Check specific activity status
var activityStatus = _fixture.GetActivityStatus(result, activity);
Assert.Equal(ActivityStatus.Completed, activityStatus);
}
}
```
{% endcode %}
#### Creating Execution Contexts
`WorkflowTestFixture` provides methods to create execution contexts at different levels:
{% code title="CreatingExecutionContexts.cs" %}
```csharp
// Create a workflow execution context
var workflowContext = await _fixture.CreateWorkflowExecutionContextAsync(
variables: new[]
{
new Variable("Counter", 0)
});
// Create an activity execution context
var activityContext = await _fixture.CreateActivityExecutionContextAsync(
activity: myActivity,
variables: new[] { new Variable("MyVar", "value") }
);
// Create an expression execution context for testing expressions
var expressionContext = await _fixture.CreateExpressionExecutionContextAsync(new[]
{
new Variable("MyVariable", "test value")
});
// Variables are accessible via dynamic accessors (e.g., getMyVariable(), setMyVariable())
var evaluator = _fixture.Services.GetRequiredService();
var script = @"
setMyVariable('updated value');
return getMyVariable();
";
var result = await evaluator.EvaluateAsync(script, typeof(string), expressionContext);
```
{% endcode %}
#### Testing Async Workflows
For workflows that complete asynchronously (with timers, external triggers, etc.), use `AsyncWorkflowRunner`:
{% code title="TestingAsyncWorkflows.cs" %}
```csharp
using Elsa.Workflows.ComponentTests.Helpers.Services;
using Xunit;
using Xunit.Abstractions;
public class AsyncWorkflowTests
{
private readonly ITestOutputHelper _testOutput;
public AsyncWorkflowTests(ITestOutputHelper testOutput)
{
_testOutput = testOutput;
}
[Fact]
public async Task AsyncWorkflow_Completes_Successfully()
{
// Arrange
var sp = new TestApplicationBuilder(_testOutput).Build();
var runner = sp.GetRequiredService();
// Act - Waits for workflow completion with timeout
var result = await runner.RunAndAwaitWorkflowCompletionAsync(
WorkflowDefinitionHandle.ByDefinitionId(workflowId, VersionOptions.Published)
);
// Assert
result.WorkflowExecutionContext.Status.Should().Be(WorkflowStatus.Finished);
result.ActivityExecutionRecords.Should().HaveCount(expectedCount);
}
}
```
{% endcode %}
`AsyncWorkflowRunner` tracks activity execution records and properly awaits workflow completion signals, making it ideal for deterministic testing of asynchronous workflow behavior.
## Integration Testing
Integration tests verify that workflows work correctly with external dependencies like databases, message queues, and HTTP services.
### Testing with TestContainers
TestContainers allows you to run real dependencies in Docker containers during tests:
{% stepper %}
{% step %}
**Install TestContainers**
```bash
dotnet add package Testcontainers
dotnet add package Testcontainers.PostgreSql
dotnet add package Testcontainers.RabbitMq
```
{% endstep %}
{% step %}
**Create Integration Test Base**
{% code title="IntegrationTestBase.cs" %}
```csharp
using DotNet.Testcontainers.Builders;
using DotNet.Testcontainers.Containers;
using Elsa.Persistence.EFCore.Extensions;
using Elsa.Persistence.EFCore.Modules.Management;
using Elsa.Persistence.EFCore.Modules.Runtime;
using Elsa.Extensions;
using Microsoft.Extensions.DependencyInjection;
using Testcontainers.PostgreSql;
using Xunit;
namespace MyWorkflows.Tests.Integration;
public abstract class IntegrationTestBase : IAsyncLifetime
{
private PostgreSqlContainer? _postgresContainer;
protected IServiceProvider Services { get; private set; } = default!;
protected string ConnectionString { get; private set; } = default!;
public virtual async Task InitializeAsync()
{
// Start PostgreSQL container
_postgresContainer = new PostgreSqlBuilder()
.WithImage("postgres:15")
.WithDatabase("elsa_test")
.WithUsername("elsa")
.WithPassword("elsa")
.Build();
await _postgresContainer.StartAsync();
ConnectionString = _postgresContainer.GetConnectionString();
// Configure services
var services = new ServiceCollection();
services.AddElsa(elsa =>
{
elsa.UseWorkflowManagement(management =>
{
management.UseEntityFrameworkCore(ef =>
ef.UsePostgreSql(ConnectionString));
});
elsa.UseWorkflowRuntime(runtime =>
{
runtime.UseEntityFrameworkCore(ef =>
ef.UsePostgreSql(ConnectionString));
});
});
ConfigureServices(services);
Services = services.BuildServiceProvider();
// Populate registries and run migrations
await Services.PopulateRegistriesAsync();
await Services.RunMigrationsAsync();
}
protected virtual void ConfigureServices(IServiceCollection services)
{
// Override in derived classes
}
public virtual async Task DisposeAsync()
{
if (Services is IDisposable disposable)
disposable.Dispose();
if (_postgresContainer != null)
await _postgresContainer.DisposeAsync();
}
}
```
{% endcode %}
{% endstep %}
{% step %}
**Write Integration Tests**
{% code title="WorkflowPersistenceTests.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Activities;
using Elsa.Workflows.Contracts;
using Elsa.Workflows.Management;
using Elsa.Workflows.Models;
using FluentAssertions;
using Microsoft.Extensions.DependencyInjection;
using Xunit;
namespace MyWorkflows.Tests.Integration;
public class WorkflowPersistenceTests : IntegrationTestBase
{
[Fact]
public async Task SaveAndLoadWorkflow_ShouldPersistCorrectly()
{
// Arrange
var workflowDefinitionService = Services.GetRequiredService();
var workflow = new WorkflowDefinition
{
DefinitionId = "test-workflow",
Name = "Test Workflow",
Version = 1,
IsLatest = true,
IsPublished = true
};
// Act - Save
await workflowDefinitionService.SaveAsync(workflow, CancellationToken.None);
// Act - Load
var loadedWorkflow = await workflowDefinitionService
.FindByDefinitionIdAsync("test-workflow", CancellationToken.None);
// Assert
loadedWorkflow.Should().NotBeNull();
loadedWorkflow!.Name.Should().Be("Test Workflow");
loadedWorkflow.Version.Should().Be(1);
}
[Fact]
public async Task ExecutePersistedWorkflow_ShouldComplete()
{
// Arrange
var workflowDefinitionService = Services.GetRequiredService();
var workflowRunner = Services.GetRequiredService();
var workflow = new Workflow
{
Identity = new WorkflowIdentity
{
DefinitionId = "simple-workflow",
Version = 1
},
Root = new WriteLine
{
Text = new Input("Integration test workflow")
}
};
// Save workflow definition
var definition = await workflowDefinitionService.SaveAsync(workflow, CancellationToken.None);
// Act - Execute
var result = await workflowRunner.RunAsync(workflow);
// Assert
result.Status.Should().Be(WorkflowStatus.Finished);
}
}
```
{% endcode %}
{% endstep %}
{% endstepper %}
### Testing HTTP Workflows
Use ASP.NET Core's test server for testing HTTP-triggered workflows:
{% code title="HttpWorkflowTests.cs" %}
```csharp
using Elsa.Extensions;
using Elsa.Http;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.TestHost;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System.Net;
using System.Net.Http.Json;
using FluentAssertions;
using Xunit;
namespace MyWorkflows.Tests.Integration;
public class HttpWorkflowTests : IAsyncLifetime
{
private IHost? _host;
private HttpClient? _client;
public async Task InitializeAsync()
{
var hostBuilder = new HostBuilder()
.ConfigureWebHost(webHost =>
{
webHost.UseTestServer();
webHost.ConfigureServices(services =>
{
services.AddElsa(elsa =>
{
elsa.UseHttp();
elsa.UseWorkflowRuntime();
});
});
webHost.Configure(app =>
{
app.UseRouting();
app.UseWorkflowsApi();
});
});
_host = await hostBuilder.StartAsync();
_client = _host.GetTestClient();
}
[Fact]
public async Task HttpEndpoint_WithValidRequest_ShouldReturnSuccess()
{
// Arrange
var request = new { name = "Test User" };
// Act
var response = await _client!.PostAsJsonAsync("/workflows/user-registration", request);
// Assert
response.StatusCode.Should().Be(HttpStatusCode.OK);
var content = await response.Content.ReadAsStringAsync();
content.Should().Contain("success");
}
public async Task DisposeAsync()
{
_client?.Dispose();
if (_host != null)
await _host.StopAsync();
}
}
```
{% endcode %}
### Testing with In-Memory Databases
For faster tests, use Entity Framework Core's in-memory database:
{% code title="InMemoryTestBase.cs" %}
```csharp
using Elsa.Persistence.EFCore.Extensions;
using Elsa.Persistence.EFCore.Modules.Management;
using Elsa.Persistence.EFCore.Modules.Runtime;
using Elsa.Extensions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Xunit;
namespace MyWorkflows.Tests.Integration;
public abstract class InMemoryTestBase : IAsyncLifetime
{
protected IServiceProvider Services { get; private set; } = default!;
public virtual async Task InitializeAsync()
{
var services = new ServiceCollection();
services.AddElsa(elsa =>
{
elsa.UseWorkflowManagement(management =>
{
management.UseEntityFrameworkCore(ef =>
ef.UseInMemory());
});
elsa.UseWorkflowRuntime(runtime =>
{
runtime.UseEntityFrameworkCore(ef =>
ef.UseInMemory());
});
});
ConfigureServices(services);
Services = services.BuildServiceProvider();
await Services.PopulateRegistriesAsync();
}
protected virtual void ConfigureServices(IServiceCollection services)
{
// Override in derived classes
}
public virtual Task DisposeAsync()
{
if (Services is IDisposable disposable)
disposable.Dispose();
return Task.CompletedTask;
}
}
```
{% endcode %}
## Debugging Workflow Execution
Debugging workflows requires understanding execution flow, state, and activity behavior.
### Using the Execution Journal
The execution journal records every activity execution, providing a complete audit trail:
{% code title="ViewExecutionJournal.cs" %}
```csharp
using Elsa.Workflows.Contracts;
using Elsa.Workflows.State;
using Microsoft.Extensions.DependencyInjection;
// After executing a workflow
var workflowRunner = serviceProvider.GetRequiredService();
var result = await workflowRunner.RunAsync(workflow);
// Access the execution journal
var journal = result.WorkflowState.ExecutionLog;
foreach (var entry in journal)
{
Console.WriteLine($"Activity: {entry.ActivityId}");
Console.WriteLine($"Event: {entry.EventName}");
Console.WriteLine($"Timestamp: {entry.Timestamp}");
Console.WriteLine($"State: {entry.Payload}");
Console.WriteLine("---");
}
```
{% endcode %}
### Logging Workflow Execution
Configure structured logging to debug workflows:
{% code title="ConfigureLogging.cs" %}
```csharp
using Elsa.Extensions;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Serilog;
var services = new ServiceCollection();
// Configure Serilog
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Debug()
.WriteTo.Console()
.WriteTo.File("logs/elsa-.txt", rollingInterval: RollingInterval.Day)
.CreateLogger();
services.AddLogging(builder =>
{
builder.ClearProviders();
builder.AddSerilog(dispose: true);
});
services.AddElsa(elsa =>
{
// Enable workflow execution logging
elsa.UseWorkflowRuntime(runtime =>
{
runtime.EnableExecutionLogging = true;
});
});
```
{% endcode %}
### Using WriteLine Activity for Debugging
Insert `WriteLine` activities to trace execution flow:
{% code title="DebugWorkflow\.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Activities;
using Elsa.Workflows.Models;
var workflow = new Workflow
{
Root = new Sequence
{
Activities =
{
new WriteLine { Text = new Input("DEBUG: Starting workflow") },
new SetVariable
{
Variable = new Variable("Counter"),
Value = new Input(0)
},
new WriteLine
{
Text = new Input(context =>
$"DEBUG: Counter value = {context.GetVariable("Counter")}")
},
new ForEach
{
Items = new Input>([1, 2, 3, 4, 5]),
Body = new Sequence
{
Activities =
{
new WriteLine
{
Text = new Input(context =>
$"DEBUG: Processing item {context.GetVariable("CurrentValue")}")
},
new SetVariable
{
Variable = new Variable("Counter"),
Value = new Input(context =>
context.GetVariable("Counter") + 1)
}
}
}
},
new WriteLine
{
Text = new Input(context =>
$"DEBUG: Final counter = {context.GetVariable("Counter")}")
},
new WriteLine { Text = new Input("DEBUG: Workflow completed") }
}
}
};
```
{% endcode %}
### Debugging with Breakpoints
Create a custom breakpoint activity for debugging:
{% code title="BreakpointActivity.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Attributes;
using System.Diagnostics;
[Activity("Debugging", "Diagnostics", "Pauses workflow execution at this point for debugging")]
public class Breakpoint : CodeActivity
{
[Input(Description = "Message to display at breakpoint")]
public Input Message { get; set; } = new("Breakpoint reached");
[Input(Description = "Enable this breakpoint")]
public Input Enabled { get; set; } = new(true);
protected override void Execute(ActivityExecutionContext context)
{
var enabled = Enabled.Get(context);
if (!enabled)
return;
var message = Message.Get(context);
// Display workflow state
Console.WriteLine($"=== BREAKPOINT ===");
Console.WriteLine($"Message: {message}");
Console.WriteLine($"Activity: {context.Activity.Id}");
Console.WriteLine($"Workflow: {context.WorkflowExecutionContext.Id}");
// Display variables
Console.WriteLine("Variables:");
var variables = context.ExpressionExecutionContext.Memory.Variables;
foreach (var variable in variables)
{
Console.WriteLine($" {variable.Key} = {variable.Value}");
}
// Launch debugger if attached
if (Debugger.IsAttached)
{
Debugger.Break();
}
else
{
Console.WriteLine("Press any key to continue...");
Console.ReadKey();
}
Console.WriteLine("=== CONTINUING ===");
}
}
```
{% endcode %}
### Inspecting Workflow State
Access and inspect workflow state during execution:
{% code title="InspectWorkflowState.cs" %}
```csharp
using Elsa.Workflows.Contracts;
using Elsa.Workflows.State;
using Microsoft.Extensions.DependencyInjection;
using System.Text.Json;
public static async Task InspectWorkflowState(IServiceProvider services, string workflowInstanceId)
{
var workflowStateStore = services.GetRequiredService();
// Load workflow state
var workflowState = await workflowStateStore.LoadAsync(workflowInstanceId);
if (workflowState == null)
{
Console.WriteLine("Workflow state not found");
return;
}
Console.WriteLine($"Workflow ID: {workflowState.Id}");
Console.WriteLine($"Status: {workflowState.Status}");
Console.WriteLine($"Sub Status: {workflowState.SubStatus}");
// Inspect variables
Console.WriteLine("\nVariables:");
foreach (var variable in workflowState.Properties)
{
Console.WriteLine($" {variable.Key} = {JsonSerializer.Serialize(variable.Value)}");
}
// Inspect bookmarks
Console.WriteLine("\nBookmarks:");
foreach (var bookmark in workflowState.Bookmarks)
{
Console.WriteLine($" Activity: {bookmark.ActivityId}");
Console.WriteLine($" Name: {bookmark.Name}");
Console.WriteLine($" Payload: {JsonSerializer.Serialize(bookmark.Payload)}");
}
// Inspect scheduled activities
Console.WriteLine("\nScheduled Activities:");
foreach (var scheduledActivity in workflowState.ScheduledActivities)
{
Console.WriteLine($" Activity: {scheduledActivity.ActivityId}");
Console.WriteLine($" Owner: {scheduledActivity.OwnerId}");
}
}
```
{% endcode %}
### Debug Workflow Failures
Handle and debug faulted workflows:
{% code title="DebugFailures.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Contracts;
using Elsa.Workflows.Models;
using Microsoft.Extensions.DependencyInjection;
public static async Task DebugFailedWorkflow(IServiceProvider services)
{
var workflowRunner = services.GetRequiredService();
var workflow = new Workflow
{
Root = new Sequence
{
Activities =
{
new WriteLine { Text = new Input("Before fault") },
new Fault
{
Message = new Input("Something went wrong!")
},
new WriteLine { Text = new Input("After fault (won't execute)") }
}
}
};
try
{
var result = await workflowRunner.RunAsync(workflow);
if (result.Status == WorkflowStatus.Faulted)
{
Console.WriteLine("Workflow faulted!");
// Get fault information
var incidents = result.WorkflowState.Incidents;
foreach (var incident in incidents)
{
Console.WriteLine($"Incident: {incident.Message}");
Console.WriteLine($"Activity: {incident.ActivityId}");
Console.WriteLine($"Exception: {incident.Exception}");
}
// Examine execution log to see what happened
foreach (var logEntry in result.WorkflowState.ExecutionLog)
{
Console.WriteLine($"{logEntry.Timestamp}: {logEntry.EventName} - {logEntry.ActivityId}");
}
}
}
catch (Exception ex)
{
Console.WriteLine($"Exception during workflow execution: {ex.Message}");
Console.WriteLine($"Stack trace: {ex.StackTrace}");
}
}
```
{% endcode %}
### Testing Faulted Workflows
When testing error scenarios, verify that workflows and activities fault correctly:
{% code title="TestingFaultedWorkflows.cs" %}
```csharp
using Elsa.Testing.Shared.Integration;
using Xunit;
public class FaultHandlingTests
{
private readonly WorkflowTestFixture _fixture;
public FaultHandlingTests(ITestOutputHelper testOutputHelper)
{
_fixture = new WorkflowTestFixture(testOutputHelper);
}
[Fact]
public async Task Activity_That_Throws_Should_Fault()
{
// Arrange
var activity = new ActivityThatThrows();
// Act
var result = await _fixture.RunActivityAsync(activity);
// Assert - Check specific activity status, not just workflow status
var activityStatus = _fixture.GetActivityStatus(result, activity);
Assert.Equal(ActivityStatus.Faulted, activityStatus);
}
[Fact]
public async Task Workflow_With_Fault_Should_Have_Incidents()
{
// Arrange
var workflow = new Workflow
{
Root = new Sequence
{
Activities =
{
new WriteLine { Text = new Input("Before fault") },
new Fault { Message = new Input("Intentional failure") }
}
}
};
// Act
var result = await _fixture.RunWorkflowAsync(workflow);
// Assert
Assert.Equal(WorkflowStatus.Faulted, result.WorkflowState.Status);
Assert.NotEmpty(result.WorkflowState.Incidents);
var incident = result.WorkflowState.Incidents.First();
Assert.Contains("Intentional failure", incident.Message);
}
}
```
{% endcode %}
When testing fault scenarios, prefer using `_fixture.GetActivityStatus(result, activity)` to check if a specific activity faulted, rather than only checking the workflow-level status. This provides more granular test assertions.
## Test Data Management
Effective test data management ensures reliable and maintainable tests.
### Test Data Builders
Use the builder pattern to create test data:
{% code title="WorkflowBuilder.cs" %}
```csharp
using Elsa.Workflows;
using Elsa.Workflows.Activities;
using Elsa.Workflows.Models;
public class TestWorkflowBuilder
{
private readonly List _activities = new();
private string _definitionId = Guid.NewGuid().ToString();
private string _name = "Test Workflow";
public TestWorkflowBuilder WithDefinitionId(string definitionId)
{
_definitionId = definitionId;
return this;
}
public TestWorkflowBuilder WithName(string name)
{
_name = name;
return this;
}
public TestWorkflowBuilder AddActivity(IActivity activity)
{
_activities.Add(activity);
return this;
}
public TestWorkflowBuilder AddWriteLine(string text)
{
_activities.Add(new WriteLine { Text = new Input(text) });
return this;
}
public TestWorkflowBuilder AddSetVariable(string variableName, object value)
{
_activities.Add(new SetVariable
{
Variable = new Variable