mock_exceptions

Visão geral do pacote

Orientação gerada a partir de informações públicas. Apenas para referência.

O pacote mock_exceptions permite que desenvolvedores simulem o comportamento de exceções em objetos falsos durante testes. Ele permite que chamadas específicas a métodos em um objeto falso ou simulado lancem exceções, o que é particularmente útil para testar cenários de tratamento de erros sem depender de implementações reais. Isso ajuda a garantir robustez nos casos de teste ao validar como o código responde a falhas. O pacote se integra perfeitamente ao ecossistema de testes do Flutter e suporta todas as principais plataformas. É ideal para testes unitários e de integração onde são necessárias condições controladas de falha.

Casos de uso

Testando caminhos de tratamento de erros
Simulando respostas de API falhas
Validando a lógica de repetição
Garantir a degradação gradual
Testando recuperação de exceção
Simulando comportamento inconsistente

Principais recursos

Injeção fácil de exceção
Suporta todas as plataformas do Flutter
Integração com classes Fake
Configuração mínima necessária
Configuração flexível de exceções
Funciona com frameworks de teste existentes

Indicado para

Testador de unidade
Testadores de integração
Desenvolvedores escrevendo código resiliente
Equipes que usam TDD/BDD
Usuários que precisam de cenários realistas de falha
Fluxos de trabalho de desenvolvimento orientado por testes

Considerações

Requer conhecimento sobre conceitos de mocking
Não destinado ao uso em produção
Depende da estrutura de teste correta
Pode aumentar a complexidade dos testes se for usado em excesso
Melhor usado junto com outras ferramentas de teste
Limitado apenas à simulação de exceção

README original

Snapshot do README original do repositório-fonte vinculado. Consulte o repositório para o conteúdo mais recente.

Provides a mechanism to throw exceptions on certain calls. This is useful when working with a Fake and we still want to occasionally make it throw exceptions. At a glance:

final f = MyFake();
whenCalling(Invocation.method(#doSomething, null))
    .on(f)
    .thenThrow(Exception());
expect(() => f.doSomething(), throwsException);

Features

supports mocking exceptions for methods, getters, setters.
supports matching on positional parameters, named parameters and type parameters (generics).
supports regular matchers.
supports omitting parameters when matching with anything.

For exhaustive usage, see our unit tests.

Differences with Mockito

Mockito lets you mock and stub methods. That means it lets you return predefined responses and throw exceptions, but not act as closely to the real thing as a Fake. Since mock_exceptions is supposed to be used on Fakes, its API unambiguously lets you mock only exceptions.

Usage

In your Fake method/getter/setter implementation, add maybeThrowException at the beginning.
In your unit test, set up an expectation, then verify your expectations as usual.

Before

Your Fake method might look like this. It does some real work.

class MyFake {
  String doSomething(String input) {
    return 'it works';
  }
}

Your unit test might even check that it works.

final fake = MyFake();
expect(fake.doSomething('yes'), 'it works');

After

Your Fake method checks for possible exceptions before doing the work.

class MyFake {
  String doSomething(String input) {
    maybeThrowException(this, Invocation.method(#doSomething, [input]));
    return 'it works';
  }
}

You can now forcefully throw exceptions and test for them.

final fake = MyFake();
whenCalling(Invocation.method(#doSomething, ['fun']))
    .on(fake)
    .thenThrow(Exception());
expect(() => fake.doSomething('fun'), throwsException);

Design considerations

whenCalling(Invocation.method(#doSomething, [equals('fun')])).on(fake).thenThrow(Exception()); is too verbose. Why not reimplement Mockito's API so that I can write when(fake.doSomething('fun')).thenThrow(Exception())?
- Implementing Mockito's API requires relying on the noSuchMethod trick to detect the Invocation. As of writing, Mockito's mock.dart takes 1200 lines of code while our mock_exceptions.dart takes around 80. Even if we pare Mockito's down to the minimum (excluding verifications, captures), it'd still take around 500 lines of code.
- It also forces the Fakes to extend a pre-defined class, Mock in Mockito's case. In some projects such as Fake Cloud Firestore (example), we actually need to extend another class.
The Mockito API has its own downsides and gotchas. See how one should use named arguments here. Also you need to use its wrappers around the regular Matchers, such as any instead of anything, and argThat(matcher).