orchestrator_test 0.3.1

Testing utilities for Orchestrator framework. Provides mocks, helpers, and custom matchers for easy unit testing of Orchestrator-based code.

orchestrator_test

A comprehensive testing toolkit for the Orchestrator framework.

Features

• Mocks - Pre-built mock implementations using mocktail
• Fakes - Lightweight fake implementations for isolated testing
• Test Helpers - BDD-style testing utilities similar to bloc_test
• Matchers - Custom matchers for event and job verification

Installation

Add orchestrator_test to your dev dependencies:

dev_dependencies:
  orchestrator_test: ^0.1.0
  test: ^1.24.0

Quick Start

Testing Orchestrators

Use testOrchestrator for BDD-style testing:

import 'package:test/test.dart';
import 'package:orchestrator_test/orchestrator_test.dart';
import 'package:my_app/orchestrators/counter_orchestrator.dart';

void main() {
  testOrchestrator<CounterOrchestrator, int>(
    'increments counter when increment is called',
    build: () => CounterOrchestrator(),
    act: (orchestrator) => orchestrator.increment(),
    expect: () => [1],
  );

  testOrchestrator<CounterOrchestrator, int>(
    'starts from seed value',
    build: () => CounterOrchestrator(),
    seed: () => 10,
    act: (orchestrator) => orchestrator.increment(),
    expect: () => [11],
  );
}

Verifying Dispatched Jobs

Use FakeDispatcher to capture and verify dispatched jobs:

import 'package:test/test.dart';
import 'package:orchestrator_test/orchestrator_test.dart';

void main() {
  late FakeDispatcher dispatcher;
  late MyOrchestrator orchestrator;

  setUp(() {
    dispatcher = FakeDispatcher();
    orchestrator = MyOrchestrator(dispatcher: dispatcher);
  });

  test('dispatches SaveJob when save is called', () {
    orchestrator.save('data');

    expect(dispatcher.dispatchedJobs, hasLength(1));
    expect(dispatcher.dispatchedJobs.first, isA<SaveJob>());
  });
}

Capturing Events

Use EventCapture to capture and wait for events:

import 'package:test/test.dart';
import 'package:orchestrator_test/orchestrator_test.dart';

void main() {
  test('emits success event after job completes', () async {
    final capture = EventCapture();

    dispatcher.dispatch(MyJob());

    final event = await capture.waitFor<JobSuccessEvent>();
    expect(event.data, equals('expected'));

    await capture.dispose();
  });
}

Testing Offline Behavior

Use FakeConnectivityProvider to simulate offline scenarios:

import 'package:test/test.dart';
import 'package:orchestrator_test/orchestrator_test.dart';

void main() {
  test('queues job when offline', () async {
    final connectivity = FakeConnectivityProvider(isOnline: false);
    OrchestratorConfig.setConnectivityProvider(connectivity);

    dispatcher.dispatch(SendMessageJob('Hello'));

    // Verify job was queued
    expect(queueManager.hasPendingJobs, isTrue);

    // Come back online
    connectivity.goOnline();
    await Future.delayed(Duration(milliseconds: 100));

    // Verify job was processed
    expect(queueManager.hasPendingJobs, isFalse);
  });
}

API Reference

Mocks

Class	Description
MockDispatcher	Mocktail mock for Dispatcher
MockSignalBus	Mocktail mock for SignalBus
MockExecutor<T>	Mocktail mock for BaseExecutor<T>

Fakes

Class	Description
FakeDispatcher	Captures dispatched jobs, simulates events
FakeSignalBus	Captures emitted events with stream support
FakeCacheProvider	In-memory cache without expiration
FakeConnectivityProvider	Simulate online/offline states
FakeNetworkQueueStorage	In-memory queue storage
FakeExecutor<T>	Captures processed jobs with custom results

Test Helpers

Function	Description
testOrchestrator	BDD-style orchestrator state testing
testOrchestratorEvents	Test orchestrator event handling
EventCapture	Capture and wait for events

Event Matchers

Matcher	Description
isJobSuccess()	Match JobSuccessEvent
isJobFailure()	Match JobFailureEvent
isJobProgress()	Match JobProgressEvent
isJobCancelled()	Match JobCancelledEvent
isJobTimeout()	Match JobTimeoutEvent
emitsEventsInOrder()	Match event sequence
emitsEventsContaining()	Match events in any order

Job Matchers

Matcher	Description
isJobOfType<T>()	Match job type
hasJobId()	Match job ID
hasTimeout()	Match job timeout
hasCancellationToken()	Match job with token
hasRetryPolicy()	Match job retry policy
containsJobOfType<T>()	List contains job type
hasJobCount<T>()	List has N jobs of type

License

MIT License - see LICENSE for details.