graftTest<G extends Graft<S>, S extends GraftState> function

void graftTest<G extends Graft<S>, S extends GraftState>(
  1. String description, {
  2. required G build(),
  3. Map<Type, Object?>? overrides,
  4. void setUp(
    1. G graft
    )?,
  5. void seed(
    1. G graft
    )?,
  6. FutureOr<void> act(
    1. G graft
    )?,
  7. Duration? wait,
  8. dynamic expect()?,
  9. dynamic expectChanges()?,
  10. dynamic errors()?,
  11. void verify(
    1. G graft
    )?,
  12. void tearDown(
    1. G graft
    )?,
  13. dynamic tags,
})

Declarative testing utility for Graft, modeled after blocTest.

Why use graftTest?

  • Blazing Fast (Sub-Millisecond): Executes pure Dart unit tests without pumping widgets or inflating elements.
  • Clean Structure: Standardizes tests into declarative phases: build, setUp, seed, act, expect, expectChanges, errors, verify, and tearDown.
  • Automatic Teardown: Automatically removes listeners and disposes the Graft instance after the test finishes, preventing memory leaks.
  • Timeouts & Delays: Easily handles asynchronous debounce or network latencies via wait.

Implementation

void graftTest<G extends Graft<S>, S extends GraftState>(
  String description, {
  required G Function() build,
  Map<Type, Object?>? overrides,
  void Function(G graft)? setUp,
  void Function(G graft)? seed,
  FutureOr<void> Function(G graft)? act,
  Duration? wait,
  dynamic Function()? expect,
  dynamic Function()? expectChanges,
  dynamic Function()? errors,
  void Function(G graft)? verify,
  void Function(G graft)? tearDown,
  dynamic tags,
}) {
  test(
    description,
    () async {
      Future<void> runTestBody() async {
        final states = <S>[];
        final graft = build();

        final originalObserver = Graft.observer;
        final testObserver = _GraftTestObserver(graft);
        Graft.observer = testObserver;

        setUp?.call(graft);
        seed?.call(graft);

        // Listen for emitted states
        void listener() {
          states.add(graft.state);
        }

        graft.addListener(listener);

        try {
          if (act != null) {
            try {
              await act(graft);
            } catch (error) {
              testObserver.errors.add(error);
            }
          }

          if (wait != null) {
            await Future.delayed(wait);
          }

          if (expect != null) {
            final expected = expect();
            expectLater(states, expected);
          }

          if (expectChanges != null) {
            final expectedChanges = expectChanges();
            expectLater(testObserver.changes, expectedChanges);
          }

          if (errors != null) {
            final expectedErrors = errors();
            expectLater(testObserver.errors, expectedErrors);
          } else if (testObserver.errors.isNotEmpty) {
            final firstError = testObserver.errors.first;
            throw firstError;
          }

          verify?.call(graft);
        } finally {
          graft.removeListener(listener);
          Graft.observer = originalObserver;
          tearDown?.call(graft);
          if (!graft.isDisposed) {
            graft.dispose();
          }
        }
      }

      if (overrides != null && overrides.isNotEmpty) {
        await runZoned(
          () => runTestBody(),
          zoneValues: {GraftDI.testZoneKey: overrides},
        );
      } else {
        await runTestBody();
      }
    },
    tags: tags,
  );
}