engineTest function

@visibleForTesting @isTest void engineTest(String description, TestCallback callback, { Engine? engine, TransportMode transportMode = TransportMode.inMemory, Map<String, dynamic>? configItems, EngineConfig? engineConfig, List<EngineOpt>? options, List<ServiceProvider>? providers, bool autoCloseEngine = false, })

Defines a single test that runs with a dedicated Engine and TestClient.

This helper ensures that the test callback is executed with full provider support, providing the correct context for routed operations.

• description: The description of the test.
• callback: The async function containing the test logic. It receives the Engine and TestClient instances.
• engine: An optional existing Engine instance to use. If not provided, a new one is created with default providers.
• client: An optional existing TestClient instance to use. If not provided, a new one is created based on transportMode.
• transportMode: The transport mode for the TestClient (defaults to inMemory).
• configItems: Initial configuration items for the Engine if a new one is created. These are passed to CoreServiceProvider.
• engineConfig: An EngineConfig instance for the Engine if a new one is created.
• options: A list of EngineOpt for the Engine if a new one is created.
• providers: Custom providers to use instead of default providers.
• autoCloseEngine: Close the provided engine after the test finishes. Engines created by this helper are always closed automatically.

Implementation

@visibleForTesting
@isTest
void engineTest(
  String description,
  TestCallback callback, {
  Engine? engine,
  TransportMode transportMode = TransportMode.inMemory,
  Map<String, dynamic>? configItems,
  EngineConfig? engineConfig,
  List<EngineOpt>? options,
  List<ServiceProvider>? providers,
  bool autoCloseEngine = false,
}) {
  test_package.test(description, () async {
    final ownsEngine = engine == null;
    final shouldCloseEngine = ownsEngine || autoCloseEngine;

    final testEngine =
        engine ??
        _createTestEngine(
          configItems: configItems,
          engineConfig: engineConfig,
          options: options,
          providers: providers,
        );

    final handler = RoutedRequestHandler(testEngine);
    final client = transportMode == TransportMode.inMemory
        ? TestClient.inMemory(handler)
        : TestClient.ephemeralServer(handler);

    try {
      // TEMP: avoid AppZone wrapping to surface zone dependencies.
      await callback(testEngine, client);
    } finally {
      await client.close();
      if (shouldCloseEngine) {
        // Ensure providers are booted before cleanup so provider teardown
        // hooks can resolve their dependencies.
        await testEngine.initialize();
        await testEngine.close();
      }
    }
  });
}