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?
answer
- sync entry point, async rule
- the throw happens only when reached
- skipped rules hide the problem
- the async test helper and a happy path
basics
~20 sThe 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 linesusing 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
Recall that MustAsync rules need ValidateAsync, and that tests use TestValidate or TestValidateAsync with ShouldHaveValidationErrorFor.
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.
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.
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.