Implement a database readiness check and test healthy, timeout, and failure states.

Create a health check that calls a narrow CanConnectAsync-style probe through an abstraction and respects cancellation. Register it with the ready tag. Liveness must not call the database. Tests use a fake probe, never the real database.

When the required database is unavailable, readiness is unhealthy so the instance receives no traffic, while liveness still proves the process itself is running.

• Keep the probe cheap and bounded.
• Return no connection strings or exception detail publicly.
• Separate readiness and liveness routes.
• Use fake dependency states in tests.

I keep the check small: one required dependency, cancellation, and a generic description. Route predicates select tagged readiness checks while liveness has no dependency checks. Operational thresholds still need tuning so one shared outage does not cause destructive restart loops.

public sealed class DatabaseReadinessCheck(IDatabaseProbe probe) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        try
        {
            return await probe.CanConnectAsync(cancellationToken)
                ? HealthCheckResult.Healthy("Database is reachable.")
                : HealthCheckResult.Unhealthy("Database is unavailable.");
        }
        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
        {
            return HealthCheckResult.Unhealthy("Database check timed out.");
        }
        catch
        {
            return HealthCheckResult.Unhealthy("Database check failed.");
        }
    }
}

services.AddHealthChecks()
    .AddCheck<DatabaseReadinessCheck>("database", tags: ["ready"]);

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = registration => registration.Tags.Contains("ready")
});
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false
});

Unit tests cover fake probe states; one deployment smoke check can verify route wiring. The readiness endpoint should be monitored for duration and flapping, not treated as a full business-flow test.

• The dependency hangs until cancellation.
• All instances share one dependency outage.
• The check throws an exception with secrets.
• Startup initialization is not yet complete.

• Use fakes for healthy, false, exception, and cancellation states.
• Assert the public response contains no exception text.
• Verify liveness never invokes the probe.

• Putting every optional dependency in readiness.
• Using the same check for liveness and readiness.
• Returning stack traces from health routes.
• Running expensive business queries on every probe.