accordant-troubleshooting

Troubleshooting Accordant

This skill covers common mistakes, debugging techniques, and how to fix typical issues.

Test Failures

"No matching expected outcome"

The response doesn't match any Expect.That() predicate.

Diagnosis:

// Check what the spec expects vs what you got
var (isValid, message, _) = spec.Allows(operation, request, actualResponse, stateProfile);
Console.WriteLine(message);  // Shows which expectation failed and why

Common causes:

1. Predicate too strict: Response has extra fields or slightly different values
2. Wrong state: The spec thinks it's in state A, but the system is in state B
3. Missing error case: You didn't handle an error condition in Apply

Fix:

// Add explanation to predicates for better debugging
Expect.That<ApiResult<User>>(
    r => r.IsSuccess && r.Data.Name == expectedName,
    $"Expected success with name '{expectedName}', got status={r?.StatusCode}, name='{r?.Data?.Name}'")

"State mismatch after operation"

Tracked state diverges from actual system state.

Common causes:

1. Forgot to reset state: Previous test left data behind
2. Missing ThenState: Operation modifies state but spec uses .SameState()
3. Wrong state update: ThenState modifies wrong fields

Fix:

// Ensure BeforeEachAsync properly resets
var results = await spec.RunTests(context, initialState, testCases, new TestExecutionOptions
{
    BeforeEachAsync = async _ =>
    {
        // Actually verify reset worked
        await client.DeleteAll();
        var count = await client.GetCount();
        if (count != 0) throw new Exception("Reset failed!");
    }
});

Tests Pass Individually, Fail in Sequence

Common causes:

1. Shared mutable state in test fixtures
2. Incomplete reset between tests
3. Timing issues with async operations

Fix:

// Create fresh client for each test
var results = await spec.RunTests(context, initialState, testCases, new TestExecutionOptions
{
    BeforeEachAsync = async ctx =>
    {
        // Fresh client, fresh start
        var httpClient = _factory.CreateClient();
        ctx.Context.Register(new ApiClient(httpClient));
        await ResetDatabase();
    }
});