stateNotifierTest<SN extends StateNotifier<State>, State> function

@isTest void stateNotifierTest<SN extends StateNotifier<State>, State>(String description, { required FutureOr actions(SN stateNotifier), FutureOr<void> setUp()?, FutureOr<void> verify(SN stateNotifier)?, FutureOr<void> tearDown()?, dynamic expect()?, Iterable<State> seed()?, int skip = 0, required SN build(), dynamic errors()?, bool expectInitialState = false, })

Creates a new stateNotifier-specific test case with the given description. stateNotifierTest will handle asserting that the stateNotifier emits the expected states (in order) after action is executed. stateNotifierTest also handles ensuring that no additional states are emitted by closing the stateNotifier stream before evaluating the expectation.

setUp is optional and should be used to set up any dependencies prior to initializing the stateNotifier under test. setUp should be used to set up state necessary for a particular test case. For common set up code, prefer to use setUp from package:test/test.dart.

build should construct and return the stateNotifier under test.

seed is an optional Function that returns an Iterable of States which will be used to seed the stateNotifier before action is called.

action is an optional callback which will be invoked with the stateNotifier under test and should be used to interaction with the stateNotifier.

skip is an optional int which can be used to skip any number of states. skip defaults to 0.

expectInitialState is an optional bool.If set to true, the initial state from the constructor will also be checked. Useful when you want to validate the initial state. Note: if set to true, it will only catch the last assigned state in the constructor. expectInitialState defaults to false.

expect is an optional Function that returns a Matcher which the stateNotifier under test is expected to emit after action is executed.

verify is an optional callback which is invoked after expect and can be used for additional verification/assertions. verify is called with the stateNotifier returned by build.

errors is an optional Function that returns a Matcher which the stateNotifier under test is expected to throw after action is executed.

tearDown is optional and can be used to execute any code after the test has run. tearDown should be used to clean up after a particular test case. For common tear down code, prefer to use tearDown from package:test/test.dart.

[stateNotifierTest] can optionally be used with one or more seeded states.

```dart
stateNotifierTest(
  'CounterNotifier emits [9,10] when seeded with 9',
  build: () => CounterNotifier(),
  seed: () => [9],
  action: (stateNotifier) => stateNotifier.increment(),
  expect: () => [9,10],
);

stateNotifierTest can also be used to skip any number of emitted states before asserting against the expected states. skip defaults to 0.

stateNotifierTest(
  'CounterNotifier emits [2] when increment is called twice',
  build: () => CounterNotifier(),
  action: (stateNotifier) {
    stateNotifier
      ..increment()
      ..increment();
  },
  skip: 1,
  expect: () => [2],
);

stateNotifierTest can also be used to verify internal stateNotifier functionality.

stateNotifierTest(
  'CounterNotifier emits [1] when increment is called',
  build: () => CounterNotifier(),
  action: (stateNotifier) => stateNotifier.increment(),
  expect: () => [1],
  verify: (_) {
    verify(() => repository.someMethod(any())).called(1);
  }
);

Note: when using stateNotifierTest with state classes which don't override == and hashCode you can provide an Iterable of matchers instead of explicit state instances.

stateNotifierTest(
 'emits [StateB] when EventB is called',
 build: () => MyBloc(),
 action: (stateNotifier) => stateNotifier.add(EventB()),
 expect: () => [isA<StateB>()],
);

Implementation

@isTest
void stateNotifierTest<SN extends StateNotifier<State>, State>(
  String description, {
  required FutureOr Function(SN stateNotifier) actions,
  FutureOr<void> Function()? setUp,
  FutureOr<void> Function(SN stateNotifier)? verify,
  FutureOr<void> Function()? tearDown,
  dynamic Function()? expect,
  Iterable<State> Function()? seed,
  int skip = 0,
  required SN Function() build,
  dynamic Function()? errors,
  bool expectInitialState = false,
}) {
  test.test(
    description,
    () async {
      await testNotifier<SN, State>(
        setUp: setUp,
        build: build,
        actions: actions,
        expect: expect,
        skip: skip,
        verify: verify,
        errors: errors,
        tearDown: tearDown,
        seed: seed,
        expectInitialState: expectInitialState,
      );
    },
  );
}