| // Copyright (c) 2026, 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 'dart:async'; | |
| import 'package:stream_channel/stream_channel.dart'; | |
| import '../backend/invoker.dart'; | |
| import '../backend/remote_exception.dart'; | |
| /// An optional fallback handler invoked when [globalSetup] is called outside | |
| /// of the full test runner (for instance, when running a test file directly via | |
| /// `dart <test_file>.dart`). | |
| Future<Object?> Function(Uri uri)? globalSetupStandaloneFallback; | |
| /// Runs a global setup Dart script at [uri] on the host test runner if it | |
| /// has not yet run, and returns its result. | |
| /// | |
| /// If multiple test suites or tests invoke [globalSetup] with the same [uri], | |
| /// the script runs only once and all callers receive the same cached result. | |
| /// Each call to [globalSetup] receives an independent copy of the value; | |
| /// mutating returned collections (such as maps or lists) does not affect other | |
| /// callers or subsequent calls. | |
| /// | |
| /// The Dart file at [uri] must define a top-level `setUp()` function that | |
| /// returns a JSON-encodable value (or `Future` of one). A `void setUp()` | |
| /// function (or one that returns `null`) is permitted and results in a `null` | |
| /// value. | |
| /// | |
| /// [globalSetup] must be called from within a running test or a `setUp()` / | |
| /// `setUpAll()` callback. It is an error to call [globalSetup] directly from | |
| /// top-level `main()`. | |
| /// | |
| /// [uri] is resolved according to the following rules: | |
| /// * **Root-relative URIs** (paths beginning with `/`, such as | |
| /// `Uri(path: '/test/setup.dart')`): | |
| /// Interpreted relative to the root of the package (the directory containing | |
| /// `pubspec.yaml`). | |
| /// * **`package:` URIs**, such as | |
| /// `Uri.parse('package:my_pkg/test_helpers.dart')`: | |
| /// Resolved using the package configuration. | |
| /// * **Relative URIs** (paths without a scheme and without a leading `/`, | |
| /// such as `Uri(path: 'setup.dart')` or `Uri(path: '../setup.dart')`): | |
| /// Interpreted relative to the directory containing the test suite file being | |
| /// executed. | |
| /// Note: When calling [globalSetup] from a shared helper library imported by | |
| /// tests in different directories, prefer root-relative (`/test/...`) or | |
| /// `package:` URIs so the path resolves consistently regardless of which | |
| /// test file imports the helper. | |
| /// * **`file:` URIs** (e.g. `Uri.file('/abs/path/setup.dart')`): | |
| /// Interpreted as absolute file paths on the filesystem. | |
| /// | |
| /// Fragments are automatically removed for consistent compilation caching. | |
| /// Relative, root-relative, and file URIs strictly prohibit query parameters. | |
| /// | |
| /// If execution fails, throws an exception containing the string representation | |
| /// and stack trace of the error thrown by the setup script. | |
| Future<Object?> globalSetup(Uri uri) async { | |
| if (Invoker.current == null) { | |
| throw StateError( | |
| 'globalSetup() ' | |
| 'must be called from within a test or setUp/setUpAll callback.', | |
| ); | |
| } | |
| final url = uri.toString(); | |
| var channel = Zone.current[#test.runner.test_channel] as MultiChannel?; | |
| if (channel == null) { | |
| var fallback = globalSetupStandaloneFallback; | |
| if (fallback != null) { | |
| return await fallback(uri); | |
| } | |
| throw UnsupportedError("Can't connect to the test runner."); | |
| } | |
| var virtualChannel = channel.virtualChannel(); | |
| channel.sink.add({ | |
| 'type': 'global-setup', | |
| 'url': url, | |
| 'channel': virtualChannel.id, | |
| }); | |
| final completer = Completer<Object?>(); | |
| late final StreamSubscription subscription; | |
| subscription = virtualChannel.stream.listen( | |
| (message) { | |
| unawaited(subscription.cancel()); | |
| switch (message) { | |
| case {'type': 'data', 'data': final data}: | |
| completer.complete(data); | |
| case {'type': 'error', 'error': final Map errorEncoding}: | |
| final error = RemoteException.deserialize(errorEncoding); | |
| completer.completeError(error.error, error.stackTrace); | |
| case _: | |
| completer.completeError( | |
| StateError( | |
| 'Unexpected message from global setup channel: $message', | |
| ), | |
| ); | |
| } | |
| }, | |
| onError: completer.completeError, | |
| onDone: () { | |
| if (!completer.isCompleted) { | |
| completer.completeError( | |
| StateError('Global setup channel closed before producing a result.'), | |
| ); | |
| } | |
| }, | |
| cancelOnError: true, | |
| ); | |
| return completer.future; | |
| } | |
| /// Registers a callback to be run during global teardown when the test runner | |
| /// closes. | |
| /// | |
| /// This must be called from within a global setup script invoked via | |
| /// [globalSetup]. | |
| /// | |
| /// It is an error if this is called outside of a global setup script. | |
| void addGlobalTearDown(FutureOr<void> Function() callback) { | |
| final list = | |
| Zone.current[#test.global_teardowns] as List<FutureOr<void> Function()>?; | |
| if (list == null) { | |
| throw UnsupportedError( | |
| 'addGlobalTearDown() ' | |
| 'can only be called from within a global setup script.', | |
| ); | |
| } | |
| list.add(callback); | |
| } |