Testando data e hora em .NET: por que DateTime.UtcNow arruína seus testes

Primeira mutação: remover a regra

Suponha que alguém apague a linha responsável pela regra:

public void ChangeName(string name)
{
    Name = name;
    // UpdatedAtUtc = DateTime.UtcNow;
}

O teste continua verde, porque UpdatedAtUtc conserva o valor do construtor, que também está no passado. Ou seja, a asserção só pergunta se o carimbo é anterior ao presente, e qualquer instante registrado satisfaz essa condição.

Segunda mutação: trocar o fuso

O segundo defeito é mais sutil e bem mais perigoso em produção:

public void ChangeName(string name)
{
    Name = name;
    UpdatedAtUtc = DateTime.Now;
}

Em um servidor no horário de Brasília, essa troca grava um valor três horas anterior ao instante real. Assim, o registro passa a ter data de alteração anterior à data de criação.

Isso quebra a ordenação cronológica, corrompe sincronizações incrementais e distorce relatórios por período. Mesmo assim, o teste segue verde, porque três horas atrás também é menor que agora.

Essas mutações mostram por que testar data e hora com o relógio real é inútil.

Elas revelam um conceito central: um teste só tem valor se consegue falhar diante de uma implementação incorreta. Na literatura de testes de mutação, esses defeitos se chamam mutantes, e a suíte acima não elimina nenhum deles.

O relógio é uma dependência oculta

Existe uma assimetria curiosa nas revisões de código. Uma entidade que abre uma conexão de banco diretamente vira alvo de crítica imediata, mas a mesma classe chama DateTime.UtcNow em cinco métodos sem que ninguém comente.

DateTime.UtcNow é uma chamada estática, então não permite substituição por polimorfismo. Além disso, ela lê estado global, o relógio mantido pelo sistema operacional.

Sobretudo, ela é entrada de dado externo, e é isso que torna difícil testar data e hora.

Ela equivale à resposta de uma API remota. Como não aparece na assinatura de nenhum método, ela se torna uma dependência oculta.

Os sintomas são reconhecíveis: testes que passam de manhã e falham à noite, ou que falham no pipeline porque o agente roda em UTC. Também aparecem quebras em 29 de fevereiro e chamadas a Thread.Sleep para esperar o tempo real passar.

Onde a dependência deve residir

Uma decisão negligenciada é onde injetar o provedor de tempo. A resposta é: o mais perto possível da borda da aplicação e o mais longe possível do domínio.

Entidades e objetos de valor não precisam conhecer o relógio. Em vez disso, elas recebem o instante relevante como parâmetro:

public class Subscription(DateTime expiresAtUtc)
{
    public DateTime ExpiresAtUtc { get; private set; } = expiresAtUtc;

    public bool IsActiveAt(DateTime utcNow) => utcNow < ExpiresAtUtc;
}

A entidade continua pura, sem contêiner, sem interface e sem configuração. Quem resolve o instante é o serviço de aplicação, que já opera na fronteira com a infraestrutura:

public class SubscriptionService(
    IDateTimeProvider dateTimeProvider,
    ISubscriptionRepository repository)
{
    public async Task<RenewalResult> RenewAsync(Guid id)
    {
        // Lê o relógio uma única vez por operação
        var now = dateTimeProvider.UtcNow;
        var subscription = await repository.GetByIdAsync(id);

        if (subscription.IsActiveAt(now))
            return RenewalResult.AlreadyActive(subscription.ExpiresAtUtc);

        subscription.RenewFrom(now, TimeSpan.FromDays(30));
        return RenewalResult.Renewed(subscription.ExpiresAtUtc);
    }
}

Repare que o serviço lê o relógio uma única vez e propaga o valor para todas as decisões seguintes. Afinal, leituras múltiplas na mesma operação podem cair em segundos diferentes e gerar inconsistências difíceis de reproduzir.

Testar data e hora com uma referência fixa

Com a dependência explícita, testar data e hora deixa de ser um palpite. Agora o teste controla o tempo em vez de consultá-lo:

private static readonly DateTime Reference =
    new(2026, 1, 15, 12, 0, 0, DateTimeKind.Utc);

[Fact(DisplayName = "Should be active when expiration is in the future")]
public void ShouldBeActiveWhenExpirationIsInTheFuture()
{
    var subscription = new Subscription(Reference.AddDays(30));

    var result = subscription.IsActiveAt(Reference);

    Assert.True(result);
}

A constante Reference congela o presente e elimina a variabilidade. Assim, se alguém inverter a comparação na implementação, o teste falha na hora.

O uso de DateTimeKind.Utc merece atenção, porque um DateTime criado sem essa indicação recebe DateTimeKind.Unspecified. Segundo a documentação, esses valores são ambíguos e conversões posteriores podem tratá-los como horário local.

Para entender melhor esses tipos, vale ler o artigo sobre DateTime no C# e .NET. Em resumo, a recomendação oficial é gravar e trafegar datas em UTC com o Kind explícito.

Testar data e hora nas fronteiras

Defeitos ligados a tempo raramente acontecem no meio de um intervalo. Na verdade, eles aparecem nos limites.

Por isso, ao testar data e hora, priorize os limites.

A pergunta quase nunca documentada é esta: no instante exato da expiração, a assinatura está ativa? Testes parametrizados transformam a resposta em especificação executável:

[Theory(DisplayName = "Should evaluate the expiration boundary correctly")]
[InlineData(-1, true)]
[InlineData(0, false)]
[InlineData(1, false)]
public void ShouldEvaluateExpirationBoundary(int offsetInSeconds, bool expected)
{
    var subscription = new Subscription(Reference);

    var result = subscription.IsActiveAt(Reference.AddSeconds(offsetInSeconds));

    Assert.Equal(expected, result);
}

Um segundo antes da expiração a assinatura está ativa, mas no instante exato e um segundo depois não está. Com isso, a regra sai da memória de alguém e passa a morar no repositório.

Além disso, Theory com InlineData evita múltiplas ações em um mesmo teste. Cada linha vira um caso independente, com falha isolada e mensagem específica.

FakeTimeProvider e o fim do Thread.Sleep

A contrapartida de teste fica no pacote Microsoft.Extensions.TimeProvider.Testing, que traz a classe FakeTimeProvider:

dotnet add package Microsoft.Extensions.TimeProvider.Testing

Sem argumentos, o FakeTimeProvider começa em 1º de janeiro de 2000, à meia-noite UTC, e não avança sozinho. Por outro lado, o construtor que recebe um DateTimeOffset fixa qualquer instante inicial, e o método Advance move o relógio de forma explícita:

private static readonly Guid UserId =
    Guid.Parse("8f14e45f-ceea-4e7a-9b1c-3d2f5a6b7c8d");

[Fact(DisplayName = "Should invalidate the token after 15 minutes")]
public void ShouldInvalidateTokenAfterFifteenMinutes()
{
    var time = new FakeTimeProvider(
        new DateTimeOffset(2026, 1, 15, 12, 0, 0, TimeSpan.Zero));
    var service = new PasswordResetService(time);
    var token = service.Generate(UserId);

    time.Advance(TimeSpan.FromMinutes(15));

    Assert.False(service.IsValid(token));
}

Quinze minutos passam em tempo de execução desprezível. Assim, não há espera, não há instabilidade e não há acoplamento à velocidade do agente de integração contínua.

O ganho vai além da leitura da hora, porque Task.Delay, Task.WaitAsync e o construtor de CancellationTokenSource aceitam um TimeProvider. Na prática, políticas de repetição e cancelamentos por tempo limite também ficam controláveis.

O FakeTimeProvider ainda permite configurar o fuso local com SetLocalTimeZone. Com isso, você consegue testar data e hora em cenários de horário de verão e de transição de fuso.

Testar data e hora em esperas assíncronas

Um caso comum é uma operação que aguarda um intervalo com Task.Delay. Nesse caso, passe o TimeProvider para a sobrecarga do método:

public class DelayedOperation(TimeProvider timeProvider)
{
    public async Task ExecuteAsync(TimeSpan delay)
    {
        // A espera usa o relógio injetado, e não o relógio real
        await Task.Delay(delay, timeProvider);
    }
}

No teste, a tarefa só termina quando o relógio falso avança o intervalo combinado:

[Fact]
public async Task DelayedOperationCompletesAfterDelay()
{
    var time = new FakeTimeProvider();
    var operation = new DelayedOperation(time);

    var task = operation.ExecuteAsync(TimeSpan.FromMinutes(5));
    Assert.False(task.IsCompleted);

    time.Advance(TimeSpan.FromMinutes(5));
    await task;

    Assert.True(task.IsCompleted);
}

Assim, você consegue testar data e hora em fluxos assíncronos sem esperar cinco minutos reais. Esse mesmo padrão vale para timeouts e políticas de repetição.

Testar data e hora com injeção de dependência

Quando o serviço vem do contêiner, registre o FakeTimeProvider como TimeProvider na coleção de serviços do teste. Dessa forma, toda a árvore de dependências passa a enxergar o relógio controlado:

var time = new FakeTimeProvider();

var services = new ServiceCollection();
services.AddSingleton<TimeProvider>(time);
services.AddSingleton<PasswordResetService>();

var provider = services.BuildServiceProvider();
var service = provider.GetRequiredService<PasswordResetService>();

Em seguida, chame Advance no mesmo objeto time para mover o relógio de todos os serviços resolvidos. Com isso, testar data e hora em testes de integração fica tão simples quanto nos testes de unidade.

Há também o método SetUtcNow, que posiciona o relógio em um instante absoluto. Ele é útil quando o cenário exige uma data específica, como o último dia de um mês.

Boas práticas da documentação oficial

A documentação do FakeTimeProvider lista recomendações que funcionam bem como checklist de revisão. Primeiro, injete sempre o TimeProvider em vez de consultar DateTime ou DateTimeOffset diretamente.

Em seguida, trabalhe em UTC e converta para horário local só na apresentação. Também exercite casos de fronteira como meia-noite, virada de mês, anos bissextos e transições de horário de verão.

Descarte os temporizadores criados por CreateTimer para evitar vazamento de recursos. Além disso, avance o tempo de forma deliberada, deixando a intenção do teste evidente.

Por fim, ao testar data e hora, não misture TimeProvider.System com FakeTimeProvider no mesmo teste. Caso contrário, o comportamento deixa de ser previsível.