skip to content

With FluentValidation, an order validator with a MustAsync rule passes its TestValidate unit tests yet throws in production. Why, and how should it be tested?

level: seniorimportance: should knowfreq 40%

answer

  1. sync entry point, async rule
  2. the throw happens only when reached
  3. skipped rules hide the problem
  4. the async test helper and a happy path

basics

~20 s

The synchronous path throws only once execution reaches an async rule. Tests that stop earlier, at a failing cascade, a false When or a null child, never reach MustAsync, but a valid production order does. Call ValidateAsync everywhere and test with TestValidateAsync, including a valid case.

solid answer

~40 s

`MustAsync`, `CustomAsync`, `WhenAsync` and `WhereAsync` make a validator asynchronous, and calling the synchronous `Validate`, or `TestValidate` in a test, throws `AsyncValidatorInvokedSynchronouslyException`. The catch is that it throws only **when execution reaches** the async component. If every test feeds invalid data that fails a cheap `NotEmpty` under `CascadeMode.Stop`, sets a `When` condition false, or leaves a child null, the async rule is skipped and the sync tests pass. Production then sends a valid order through a synchronous call and throws. The fix is to call `ValidateAsync` on every path, test with `TestValidateAsync`, and always include a valid case that reaches the async rule. Assertions use `ShouldHaveValidationErrorFor`, `WithErrorCode`, `Only()` and `ShouldNotHaveAnyValidationErrors`, with the validator's dependency faked rather than the validator mocked.

code

csharp · 57 lines
csharp
using FluentValidation;
using FluentValidation.TestHelper;

public interface ICustomerDirectory
{
    Task<bool> ExistsAsync(string customerId, CancellationToken ct);
}

public class CreateOrderCommand
{
    public string CustomerId { get; set; } = "";
}

public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator(ICustomerDirectory customers)
    {
        RuleFor(x => x.CustomerId)
            .Cascade(CascadeMode.Stop)
            .NotEmpty()
            .MustAsync((id, ct) => customers.ExistsAsync(id, ct))
            .WithMessage("Customer {PropertyValue} does not exist.");
    }
}

public class FixedDirectory(bool exists) : ICustomerDirectory
{
    public Task<bool> ExistsAsync(string customerId, CancellationToken ct) => Task.FromResult(exists);
}

public static class CreateOrderCommandValidatorTests
{
    // Passes, but never reaches MustAsync: NotEmpty fails first and Cascade(Stop) ends the rule.
    public static void Empty_id_fails()
    {
        var result = new CreateOrderCommandValidator(new FixedDirectory(true))
            .TestValidate(new CreateOrderCommand { CustomerId = "" });
        result.ShouldHaveValidationErrorFor(x => x.CustomerId).WithErrorCode("NotEmptyValidator");
    }

    // Reaches MustAsync, so it must use the async helper.
    public static async Task Unknown_customer_fails()
    {
        var result = await new CreateOrderCommandValidator(new FixedDirectory(false))
            .TestValidateAsync(new CreateOrderCommand { CustomerId = "C-1042" });
        result.ShouldHaveValidationErrorFor(x => x.CustomerId)
            .WithErrorCode("AsyncPredicateValidator")
            .Only();
    }

    public static async Task Valid_order_passes()
    {
        var result = await new CreateOrderCommandValidator(new FixedDirectory(true))
            .TestValidateAsync(new CreateOrderCommand { CustomerId = "C-1042" });
        result.ShouldNotHaveAnyValidationErrors();
    }
}

go deeper

for a junior

Recall that MustAsync rules need ValidateAsync, and that tests use TestValidate or TestValidateAsync with ShouldHaveValidationErrorFor.

for a middle

Explain that the synchronous path throws only when it reaches an async component, and list what can skip it: cascade Stop, a false When, an excluded rule set, a null child.

for a senior

Diagnose the green-tests, failing-production pattern quickly and prescribe the suite: async helpers, a valid case per validator, an async-failing case per async rule, faked dependencies.

for a principal

Turn it into team policy: validators are always invoked with ValidateAsync, and validator tests must include a happy path, so no synchronous caller can slip in unnoticed.

FluentValidation, the .NET library that defines validation rules in a separate validator class, supports **asynchronous rules** for checks that must await something, such as "does this customer exist?". It also ships a **test helper** for asserting on a validator's results. The two meet in a failure that is easy to ship: a validator whose tests are green and which throws on the first real request. ## Which rules are asynchronous These methods add an asynchronous component to a validator: - `MustAsync((value, cancellationToken) => ...)`, the async form of `Must`, with overloads that also receive the root object and the `ValidationContext<T>`; - `CustomAsync(...)`, the async form of `Custom`; - `WhenAsync` and `UnlessAsync`, asynchronous conditions; - `WhereAsync`, the asynchronous filter on a `RuleForEach` collection rule. A validator containing any of them must be run with **`ValidateAsync`**, which runs both synchronous and asynchronous rules. The library's documentation says to always call `ValidateAsync` on such a validator and never `Validate`, which throws. ## Why the tests stayed green The synchronous path does not inspect the validator up front. It throws `AsyncValidatorInvokedSynchronouslyException` at the moment it **reaches** an async component, and the message tells you to call `ValidateAsync` rather than `Validate`. Anything that stops execution before that point hides the problem: 1. **Cascade.** With `CascadeMode.Stop` on `RuleFor(x => x.CustomerId).NotEmpty().MustAsync(CustomerExists)`, a test that passes an empty ID fails at `NotEmpty` and never reaches `MustAsync`. 2. **Conditions.** A `When(x => x.IsNewCustomer)` that is false in every test skips the async rule. 3. **Rule sets.** If the async rule sits in a rule set the test does not include, it never runs. 4. **Null children.** An async rule inside a child validator is never reached when the test leaves that child null. The tests call `TestValidate`, which also runs synchronously, so a suite made only of "bad input" cases can pass forever. The first valid order in production reaches `MustAsync` through a synchronous `Validate` call and throws. The same happens with any synchronous pipeline that invokes the validator, which is why automatic validation through a synchronous framework pipeline is a poor fit for async rules. ## Testing the validator properly The test helper lives in the `FluentValidation.TestHelper` namespace: | Method | Purpose | |---|---| | `TestValidate(model)` | runs `Validate`, returns a `TestValidationResult<T>` | | `TestValidateAsync(model)` | runs `ValidateAsync`, for any validator with async rules | | `ShouldHaveValidationErrorFor(x => x.CustomerId)` | asserts a failure on that property | | `ShouldHaveValidationErrorFor("LineItems[0].Quantity")` | the same with a string path, for nested or indexed members | | `.WithErrorCode(...)`, `.WithErrorMessage(...)`, `.Only()` | narrow the assertion; `Only()` fails if other failures exist | | `ShouldNotHaveValidationErrorFor(...)`, `ShouldNotHaveAnyValidationErrors()` | assert the absence of failures | A failed assertion throws a `ValidationTestException`. If `TestValidate` reaches an async rule, it throws too, with a message saying the validator contains asynchronous rules and that the asynchronous test methods should be used. Rules for a validator test suite that would have caught the bug: - Use `TestValidateAsync` for any validator with an async component, and `ValidateAsync` in production code. - Include at least one **fully valid** input per validator, asserting `ShouldNotHaveAnyValidationErrors()`. It is the case that walks every rule to the end. - For each async rule, include an input that passes the cheap checks and fails the async one, so the async branch is exercised. - Pass a `CancellationToken` through; `MustAsync` receives it. ## Treat the validator as a black box FluentValidation's documentation recommends testing validators with real instances and known bad data, not mocking them, because a mock encodes assumptions about the library's internals. For the async dependency, inject an interface you own into the validator's constructor and give the test a **fake implementation** returning a fixed answer. When some other code under test needs an `IValidator<T>` stub, the documentation suggests an `InlineValidator<T>` with a rule that always fails, instead of a mocking library. ## The checklist in short - Async component present means `ValidateAsync` everywhere. - A sync test that passes proves nothing about rules it never reached. - One valid case per validator and one async-failing case per async rule. - Fake the validator's dependency; do not mock the validator.

  • With FluentValidation, does ValidateAsync also run the synchronous rules?
    Yes. `ValidateAsync` runs every rule, synchronous and asynchronous, so a validator with even one async component can be run entirely through it. The reverse does not hold: synchronous `Validate` throws `AsyncValidatorInvokedSynchronouslyException` as soon as it reaches an async rule or async condition.
  • With FluentValidation, why does the documentation advise against mocking a validator in tests?
    Because a mock has to assume how the validator is built, both its rules and the library's internals, which makes tests brittle and unsafe across upgrades. Test a real validator with known bad data instead. When code under test needs a stub `IValidator<T>`, use an `InlineValidator<T>` with a rule such as `Must(_ => false)`, so failures are created by the library itself.

  • FluentValidation checks for async rules up front, so any Validate call on such a validator throws.
  • Validate quietly awaits a MustAsync rule, so the sync call is fine.
  • TestValidate runs async rules automatically, so TestValidateAsync is optional.
  • A passing suite of invalid-input tests proves every rule in the validator works.
  • The cleanest validator test mocks IValidator<T> with a mocking library.