Testing Riverpod Providers: A Complete Guide

Introduction to Riverpod

Riverpod is a reactive Caching and Data-binding Framework which can be used as powerful state management library for Flutter and Dart applications, created by Remi Rousselet, the author of the popular Provider package. It addresses several limitations of Provider and offers significant advantages:

Compile-time safety: Riverpod catches many errors at compile-time rather than runtime.

Testability: It provides excellent support for unit testing and widget testing.

Flexibility: Riverpod allows for easy creation and combination of providers.
Improved performance: It optimizes rebuilds and allows for more granular control over state updates.

Riverpod is designed to work seamlessly with the Flutter framework but can also be used in pure Dart applications. It provides a set of tools to manage application state, from simple values to complex asynchronous data flows.

ProviderContainer and Testing Utilities

Before diving into specific provider types, it's crucial to understand the tools Riverpod offers for testing.

ProviderContainer

ProviderContainer is a fundamental class in Riverpod for testing purposes. It allows you to create an isolated environment for your providers, separate from the widget tree. This isolation is essential for unit testing providers without the need for a full widget test setup.

Key points about ProviderContainer:

It holds the state of all providers created within it.
It allows you to read and interact with providers outside of a widget context.
It supports overrides, enabling you to replace providers with mocks or different implementations for testing.

createContainer Utility

To streamline the creation of ProviderContainer instances in tests, you can use a utility function like createContainer:

ProviderContainer createContainer({
  ProviderContainer? parent,
  List<Override> overrides = const [],
  List<ProviderObserver>? observers,
}) {
  final container = ProviderContainer(
    parent: parent,
    overrides: overrides,
    observers: observers,
  );

  addTearDown(container.dispose);

  return container;
}

This utility function:

Creates a new ProviderContainer with optional parameters for parent, overrides, and observers.
Automatically adds a teardown step to dispose of the container after the test, preventing memory leaks.
Provides a consistent way to create containers across your test suite.

Overrides in Riverpod Testing

Overrides are a powerful feature in Riverpod that allow you to replace the implementation of a provider for testing purposes. This is particularly useful for:

Mocking dependencies
Testing different scenarios by providing different initial values
Isolating parts of your application for focused testing

Types of Riverpod Providers and How to Test Them

1. Provider

What is it?

Provider is the most basic type of provider in Riverpod. It creates a value that doesn't change over time.

When to use it?

Use Provider for:

Dependency injection
Computed values that don't change
Singleton instances

Testing Provider

final apiClientProvider = Provider<ApiClient>((ref) => ApiClient());

void main() {
  test('apiClientProvider returns a singleton instance', () {
    final container = createContainer();

    final instance1 = container.read(apiClientProvider);
    final instance2 = container.read(apiClientProvider);

    expect(instance1, isA<ApiClient>());
    expect(identical(instance1, instance2), true);
  });
}

Why test this way?

We use createContainer to isolate the provider from the rest of the app.
We verify that the provider returns the correct type of object.
We check that multiple reads return the same instance, ensuring it's a singleton.

2. StateProvider

What is it?

StateProvider is used for simple state that can change over time.

When to use it?

Use StateProvider for:

Simple state that can be represented by a single value
State that doesn't require complex logic to update

Testing StateProvider

final counterStateProvider = StateProvider<int>((ref) => 0);

void main() {
  test('counterStateProvider can be incremented and reset', () {
    final container = createContainer();

    expect(container.read(counterStateProvider), 0);

    container.read(counterStateProvider.notifier).state++;
    expect(container.read(counterStateProvider), 1);

    container.read(counterStateProvider.notifier).state = 0;
    expect(container.read(counterStateProvider), 0);
  });
}

Why test this way?

We test the initial state to ensure correct initialization.
We modify the state and verify it changes correctly.
We test resetting the state to ensure all state changes work as expected.

3. StateNotifierProvider

What is it?

StateNotifierProvider is used for more complex state management, allowing you to define methods to change the state.

When to use it?

Use StateNotifierProvider for:

Complex state that requires custom logic to update
State that needs to be modified through specific methods

Testing StateNotifierProvider

class Counter extends StateNotifier<int> {
  Counter() : super(0);
  void increment() => state++;
  void decrement() => state--;
}

final counterNotifierProvider = StateNotifierProvider<Counter, int>((ref) => Counter());

void main() {
  test('counterNotifierProvider handles state changes correctly', () {
    final container = createContainer();

    expect(container.read(counterNotifierProvider), 0);

    container.read(counterNotifierProvider.notifier).increment();
    expect(container.read(counterNotifierProvider), 1);

    container.read(counterNotifierProvider.notifier).decrement();
    expect(container.read(counterNotifierProvider), 0);
  });
}

Why test this way?

We test the initial state.
We test each method of the StateNotifier to ensure they modify the state correctly.
We verify that the state is accessible both through the provider and its notifier.

4. NotifierProvider

What is it?

NotifierProvider is a more recent addition to Riverpod, introduced as an alternative to StateNotifierProvider. It offers a simpler API and better type inference.

When to use it?

Use NotifierProvider for:

Complex state management where you need custom methods to update the state
Situations where you want to avoid the boilerplate of extending StateNotifier

Testing NotifierProvider

class CounterNotifier extends Notifier<int> {
  @override
  int build() => 0;

  void increment() => state++;
  void decrement() => state--;
}

final counterNotifierProvider = NotifierProvider<CounterNotifier, int>(() => CounterNotifier());

void main() {
  test('counterNotifierProvider handles state changes correctly', () {
    final container = createContainer();

    expect(container.read(counterNotifierProvider), 0);

    container.read(counterNotifierProvider.notifier).increment();
    expect(container.read(counterNotifierProvider), 1);

    container.read(counterNotifierProvider.notifier).decrement();
    expect(container.read(counterNotifierProvider), 0);
  });
}

Why test this way?

We test the initial state provided by the build method.
We test each method of the Notifier to ensure they modify the state correctly.
We verify that the state is accessible both through the provider and its notifier.

5. AsyncNotifierProvider

What is it?

AsyncNotifierProvider is used for managing asynchronous state with more complex logic. It's similar to NotifierProvider but designed specifically for asynchronous operations.

When to use it?

Use AsyncNotifierProvider for:

Complex asynchronous state management
Scenarios where you need to handle loading, error, and data states
Operations that involve API calls or other asynchronous tasks

Testing AsyncNotifierProvider

Let's create an example AsyncNotifier and then test it:

class UserAsyncNotifier extends AsyncNotifier<User> {
  @override
  Future<User> build() async {
    // Simulating an API call
    await Future.delayed(Duration(seconds: 1));
    return User('Initial User');
  }

  Future<void> updateUser(String newName) async {
    state = const AsyncValue.loading();
    try {
      // Simulating an API call
      await Future.delayed(Duration(seconds: 1));
      state = AsyncValue.data(User(newName));
    } catch (e, st) {
      state = AsyncValue.error(e, st);
    }
  }
}

final userAsyncNotifierProvider = AsyncNotifierProvider<UserAsyncNotifier, User>(() => UserAsyncNotifier());

class User {
  final String name;
  User(this.name);
}

// Test
import 'package:flutter_test/flutter_test.dart';
import 'package:hooks_riverpod/hooks_riverpod.dart';

void main() {
  test('UserAsyncNotifier initializes and updates correctly', () async {
    final container = createContainer();

    // Test initial state
    expect(container.read(userAsyncNotifierProvider), const AsyncValue<User>.loading());

    // Wait for the build method to complete
    await container.read(userAsyncNotifierProvider.future);

    // Check the initial user
    final initialUser = container.read(userAsyncNotifierProvider).value;
    expect(initialUser?.name, 'Initial User');

    // Update the user
    final notifier = container.read(userAsyncNotifierProvider.notifier);
    notifier.updateUser('New User');

    // Check loading state
    expect(container.read(userAsyncNotifierProvider), const AsyncValue<User>.loading());

    // Wait for the update to complete
    await Future.delayed(Duration(seconds: 2));

    // Check the updated user
    final updatedUser = container.read(userAsyncNotifierProvider).value;
    expect(updatedUser?.name, 'New User');
  });

  test('UserAsyncNotifier handles errors', () async {
    final container = createContainer();

    // Override the provider to simulate an error
    final errorProvider = AsyncNotifierProvider<UserAsyncNotifier, User>(() {
      return UserAsyncNotifier()
        ..updateUser = (String newName) async {
          throw Exception('Update failed');
        };
    });

    // Wait for the initial build
    await container.read(errorProvider.future);

    // Attempt to update, which should cause an error
    final notifier = container.read(errorProvider.notifier);
    await notifier.updateUser('Error User');

    // Check that the state is an error
    final errorState = container.read(errorProvider);
    expect(errorState, isA<AsyncError>());
    expect(errorState.error, isA<Exception>());
    expect((errorState.error as Exception).toString(), 'Exception: Update failed');
  });
}

Why test this way?

We test the initial loading state and the result of the build method.
We verify that the updateUser method correctly transitions through loading and data states.
We test error handling by overriding the provider to simulate an error condition.
We check all possible states: loading, data, and error.

Key Points for Testing AsyncNotifierProvider

Initial State: Always check the initial loading state before the build method completes.
State Transitions: Verify that the state correctly transitions through loading, data, and error states.
Error Handling: Test error scenarios by simulating failures in your async operations.
Timing: Use Future.delayed or similar methods to allow for asynchronous operations to complete.
State Access: Access the current state using container.read(provider) and the notifier using container.read(provider.notifier).

Testing AsyncNotifierProvider thoroughly ensures that your application can handle complex asynchronous workflows correctly, including proper error management and state transitions.

6. FutureProvider

What is it?

FutureProvider is used for asynchronous operations that don't need to be refreshed frequently.

When to use it?

Use FutureProvider for:

API calls that don't need real-time updates
Loading data that's fetched once and then cached

Testing FutureProvider

final userProvider = FutureProvider<User>((ref) async {
  await Future.delayed(Duration(seconds: 1)); // Simulating network delay
  return User('John Doe');
});

void main() {
  test('userProvider loads data correctly', () async {
    final container = createContainer();

    expect(container.read(userProvider), const AsyncValue<User>.loading());

    await container.read(userProvider.future);

    final value = container.read(userProvider);
    expect(value, isA<AsyncData<User>>());
    expect(value.value?.name, 'John Doe');
  });
}

Why test this way?

We check the initial loading state.
We await the future to complete.
We verify the loaded data is correct and in the expected AsyncValue wrapper.

7. StreamProvider

What is it?

StreamProvider is used for asynchronous data that changes over time.

When to use it?

Use StreamProvider for:

Real-time data updates (e.g., WebSocket connections)
Observing changes in databases or other data sources

Testing StreamProvider

final countStreamProvider = StreamProvider<int>((ref) {
  return Stream.periodic(Duration(seconds: 1), (i) => i).take(3);
});

void main() {
  test('countStreamProvider emits values correctly', () async {
    final container = createContainer();

    expect(container.read(countStreamProvider), const AsyncValue<int>.loading());

    await expectLater(
      container.stream(countStreamProvider.future),
      emitsInOrder([0, 1, 2]),
    );

    final finalValue = container.read(countStreamProvider);
    expect(finalValue, isA<AsyncData<int>>());
    expect(finalValue.value, 2);
  });
}

Why test this way?

We check the initial loading state.
We use expectLater to verify the stream emits the expected sequence of values.
We check the final state to ensure it reflects the last emitted value.

8. Family Providers

What is it?

Family providers allow you to create providers that take parameters.

When to use it?

Use Family providers when:

You need to create multiple instances of a provider with different parameters
The provider depends on external data not available at compile-time

Testing Family Providers

final userFamilyProvider = FutureProvider.family<User, String>((ref, userId) async {
  await Future.delayed(Duration(seconds: 1)); // Simulating network delay
  return User(userId);
});

void main() {
  test('userFamilyProvider loads different users based on parameter', () async {
    final container = createContainer();

    final user1Future = container.read(userFamilyProvider('user1').future);
    final user2Future = container.read(userFamilyProvider('user2').future);

    final user1 = await user1Future;
    final user2 = await user2Future;

    expect(user1.id, 'user1');
    expect(user2.id, 'user2');
  });
}

Why test this way?

We test multiple instances of the family provider with different parameters.
We ensure that each instance returns the correct data based on its parameter.
We verify that family providers can be used concurrently without interference.

Advanced Testing Techniques

Using Overrides for Mocking

Overrides are particularly useful when you need to mock dependencies or test different scenarios. Here's an example:

final apiClientProvider = Provider<ApiClient>((ref) => RealApiClient());

final userProvider = FutureProvider<User>((ref) async {
  final client = ref.watch(apiClientProvider);
  return client.fetchUser();
});

test('userProvider fetches user correctly', () async {
  final mockClient = MockApiClient();
  when(mockClient.fetchUser()).thenAnswer((_) async => User('Test User'));

  final container = createContainer(
    overrides: [
      apiClientProvider.overrideWithValue(mockClient),
    ],
  );

  final user = await container.read(userProvider.future);
  expect(user.name, 'Test User');
});

In this example, we're overriding the apiClientProvider with a mock implementation, allowing us to test the userProvider in isolation without making real API calls.

Widget testing is crucial for ensuring that your UI components behave correctly when integrated with Riverpod providers. Let's explore how to effectively test widgets that use Riverpod, utilizing some helpful extensions from your testing utilities.

WidgetTester Extensions

First, let's look at the useful extensions you've defined for WidgetTester:

extension WidgetTesterX on WidgetTester {
  /// Calls [pumpWidget] with the [widget] wrapped in a [MaterialApp].
  Future<void> pumpMaterialWidget(
    Widget widget, [
    Duration? duration,
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
  ]) =>
      pumpWidget(MaterialApp(home: widget));

  /// Calls [pumpWidget] with the [widget] wrapped in a [MaterialApp] and scoped
  /// with a [ProviderScope].
  ///
  /// The [overrides] and [observers] values will be passed to
  /// the [ProviderScope].
  Future<void> pumpMaterialWidgetScoped(
    Widget widget, {
    Duration? duration,
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
    List<Override> overrides = const [],
    List<ProviderObserver>? observers,
  }) =>
      pumpWidget(
        ProviderScope(
          overrides: overrides,
          observers: observers,
          child: MaterialApp(home: widget),
        ),
      );
}

These extensions provide convenient methods for pumping widgets wrapped in a MaterialApp and ProviderScope, which is essential for testing Riverpod-dependent widgets.

Let's create an example widget that uses a Riverpod provider and then test it:

// counter_widget.dart
import 'package:flutter/material.dart';
import 'package:hooks_riverpod/hooks_riverpod.dart';

final counterProvider = StateProvider((ref) => 0);

class CounterWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Text('Count: $count'),
        ElevatedButton(
          onPressed: () => ref.read(counterProvider.notifier).state++,
          child: Text('Increment'),
        ),
      ],
    );
  }
}

Now, let's write a test for this widget:

// counter_widget_test.dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:hooks_riverpod/hooks_riverpod.dart';
import 'package:your_app/counter_widget.dart';
import 'package:your_app/test/utils/testing_utils.dart';

void main() {
  testWidgets('CounterWidget displays count and increments', (WidgetTester tester) async {
    await tester.pumpMaterialWidgetScoped(CounterWidget());

    // Check initial state
    expect(find.text('Count: 0'), findsOneWidget);

    // Tap the increment button
    await tester.tap(find.byType(ElevatedButton));
    await tester.pump();

    // Check updated state
    expect(find.text('Count: 1'), findsOneWidget);
  });

  testWidgets('CounterWidget with initial value override', (WidgetTester tester) async {
    await tester.pumpMaterialWidgetScoped(
      CounterWidget(),
      overrides: [
        counterProvider.overrideWith((ref) => 10),
      ],
    );

    // Check initial state with override
    expect(find.text('Count: 10'), findsOneWidget);
  });
}

1. Use pumpMaterialWidgetScoped: This extension method wraps your widget in both a MaterialApp and a ProviderScope, which is necessary for most Riverpod-based widgets.

Overrides for Testing: You can pass overrides to pumpMaterialWidgetScoped to replace providers with test-specific values or mocks.
Interacting with Widgets: Use tester.tap(), tester.enterText(), etc., to interact with your widgets, then use tester.pump() or tester.pumpAndSettle() to rebuild the widget tree.
Verifying UI Updates: After interactions, check that the UI has updated correctly using expect() and finder methods.
Testing Different Scenarios: Create multiple test cases to cover different initial states, user interactions, and edge cases.

Testing Asynchronous Widgets

For widgets that depend on asynchronous providers (like FutureProvider or StreamProvider), you may need to use tester.pumpAndSettle() or manually pump with a duration to allow for asynchronous operations to complete:

testWidgets('AsyncCounterWidget displays loading and then value', (WidgetTester tester) async {
  final asyncCounterProvider = FutureProvider((ref) async {
    await Future.delayed(Duration(seconds: 1));
    return 42;
  });

  await tester.pumpMaterialWidgetScoped(
    Consumer(builder: (context, ref, _) {
      final asyncValue = ref.watch(asyncCounterProvider);
      return asyncValue.when(
        data: (value) => Text('Count: $value'),
        loading: () => CircularProgressIndicator(),
        error: (_, __) => Text('Error'),
      );
    }),
  );

  // Initially, we should see a loading indicator
  expect(find.byType(CircularProgressIndicator), findsOneWidget);

  // Wait for the future to complete
  await tester.pumpAndSettle(Duration(seconds: 2));

  // Now we should see the value
  expect(find.text('Count: 42'), findsOneWidget);
});

By incorporating these widget testing techniques with Riverpod, you can ensure that your UI components interact correctly with your state management logic, leading to more robust and reliable Flutter applications.

Best Practices for Riverpod Testing

Isolation: Always use createContainer to isolate providers during testing.
Disposal: The createContainer utility automatically handles disposal, but ensure you're not keeping references that prevent garbage collection.
Async Handling: For async providers, use expectLater or await appropriately.
State Changes: Test both initial states and state transitions.
Mocking and Overrides: Use overrides in createContainer to mock dependencies or provide test-specific implementations. This allows you to isolate the component under test and control its environment.
Comprehensive Coverage: Test edge cases and error scenarios, not just the happy path.
Readability: Structure tests in a "Arrange-Act-Assert" pattern for clarity.

Conclusion

By understanding Riverpod's core concepts, including ProviderContainer, overrides, and the various provider types, you can create a comprehensive and robust test suite. The createContainer utility and judicious use of overrides allow you to precisely control the testing environment, focusing on specific behaviors without unnecessary dependencies.

This approach leads to more reliable, maintainable, and performant Flutter applications. As Riverpod continues to evolve, always refer to the official documentation for the most up-to-date information and advanced usage patterns.

Command Palette

Comments (1)

More from this blog

Introduction to Riverpod

ProviderContainer and Testing Utilities

ProviderContainer

createContainer Utility

Overrides in Riverpod Testing

Types of Riverpod Providers and How to Test Them

1. Provider

What is it?

When to use it?

Testing Provider

Why test this way?

2. StateProvider

What is it?

When to use it?

Testing StateProvider

Why test this way?

3. StateNotifierProvider

What is it?

When to use it?

Testing StateNotifierProvider

Why test this way?

4. NotifierProvider

What is it?

When to use it?

Testing NotifierProvider

Why test this way?

5. AsyncNotifierProvider

What is it?

When to use it?

Testing AsyncNotifierProvider

Why test this way?

Key Points for Testing AsyncNotifierProvider

6. FutureProvider

What is it?

When to use it?

Testing FutureProvider

Why test this way?

7. StreamProvider

What is it?

When to use it?

Testing StreamProvider

Why test this way?

8. Family Providers

What is it?

When to use it?

Testing Family Providers

Why test this way?

Advanced Testing Techniques

Using Overrides for Mocking

Widget Testing with Riverpod

WidgetTester Extensions

Testing a Widget with Riverpod

Key Points for Widget Testing with Riverpod

Testing Asynchronous Widgets

Best Practices for Riverpod Testing

Conclusion