| // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file |
| // for details. All rights reserved. Use of this source code is governed by a |
| // BSD-style license that can be found in the LICENSE file. |
| |
| import 'package:stream_channel/stream_channel.dart'; |
| |
| import 'package:test_api/src/backend/suite_platform.dart'; // ignore: implementation_imports |
| import 'suite.dart'; |
| import 'runner_suite.dart'; |
| import 'environment.dart'; |
| |
| /// A class that defines a platform for which test suites can be loaded. |
| /// |
| /// A minimal plugin must define [loadChannel], which connects to a client in |
| /// which the tests are defined. This is enough to support most of the test |
| /// runner's functionality. |
| /// |
| /// In order to support interactive debugging, a plugin must override [load] as |
| /// well, which returns a [RunnerSuite] that can contain a custom [Environment] |
| /// and control debugging metadata such as [RunnerSuite.isDebugging] and |
| /// [RunnerSuite.onDebugging]. The plugin must create this suite by calling the |
| /// [deserializeSuite] helper function. |
| /// |
| /// A platform plugin can be registered by passing it to [new Loader]'s |
| /// `plugins` parameter. |
| abstract class PlatformPlugin { |
| /// Loads and establishes a connection with the test file at [path] using |
| /// [platform]. |
| /// |
| /// This returns a channel that's connected to a remote client. The client |
| /// must connect it to a channel returned by [serializeGroup]. The default |
| /// implementation of [load] will take care of wrapping it up in a |
| /// [RunnerSuite] and running the tests when necessary. |
| /// |
| /// The returned channel may emit exceptions, indicating that the suite failed |
| /// to load or crashed later on. If the channel is closed by the caller, that |
| /// indicates that the suite is no longer needed and its resources may be |
| /// released. |
| /// |
| /// The `platform.platform` is guaranteed to be one of the platforms |
| /// associated with this plugin in [new Loader]'s `plugins` parameter. |
| // TODO(grouma) - Remove this method from the API as no platforms implement |
| // it. |
| StreamChannel<dynamic> loadChannel(String path, SuitePlatform platform); |
| |
| /// Loads the runner suite for the test file at [path] using [platform], with |
| /// [suiteConfig] encoding the suite-specific configuration. |
| /// |
| /// By default, this just calls [loadChannel] and passes its result to |
| /// [deserializeSuite]. However, it can be overridden to provide more |
| /// fine-grained control over the [RunnerSuite], including providing a custom |
| /// implementation of [Environment]. |
| /// |
| /// Subclasses overriding this method must call [deserializeSuite] in |
| /// `platform_helpers.dart` to obtain a [RunnerSuiteController]. They must |
| /// pass the opaque [message] parameter to the [deserializeSuite] call. |
| Future<RunnerSuite?> load(String path, SuitePlatform platform, |
| SuiteConfiguration suiteConfig, Map<String, Object?> message); |
| |
| Future closeEphemeral() async {} |
| |
| Future close() async {} |
| } |