riverpod-testing

Riverpod — Testing

Instructions

Riverpod is designed for testability: isolate state per test, mock via overrides, and keep the test environment close to production.

Unit tests (no Flutter)

Use ProviderContainer.test() to create a container for the test. Do not share containers between tests.

void main() {
  test('Some description', () {
    final container = ProviderContainer.test();
    expect(container.read(provider), equals('some value'));
  });
}

• container.read(provider) — Read current value.
• container.listen(provider, (prev, next) {}) — Listen and get a subscription; use subscription.read() to read. Prefer listen when the provider is auto-dispose so it is not disposed mid-test.

final subscription = container.listen<String>(provider, (_, _) {});
expect(subscription.read(), 'Some value');

Widget tests

Wrap the widget under test in ProviderScope:

testWidgets('Some description', (tester) async {
  await tester.pumpWidget(
    const ProviderScope(child: YourWidgetYouWantToTest()),
  );
});

To interact with providers in the test, get the container with tester.container():

final container = tester.container();
expect(container.read(provider), 'some value');

Mocking providers

Use overrides on ProviderContainer or ProviderScope. All providers can be overridden without extra setup.

final container = ProviderContainer.test(
  overrides: [
    exampleProvider.overrideWith((ref) => 'Hello from tests'),
  ],
);

// Or in widget tests:
await tester.pumpWidget(
  ProviderScope(
    overrides: [exampleProvider.overrideWith((ref) => 'Hello from tests')],
    child: const YourWidgetYouWantToTest(),
  ),
);

See riverpod-overrides for family overrides and other override methods.

Awaiting async providers

Read provider.future to get a Future that completes with the provider value; use with expectLater:

await expectLater(
  container.read(provider.future),
  completion('some value'),
);