Test

https://pub.dev/documentation/test/latest
Admin
Test is a standard testing package for Dart that provides a framework for writing and running unit...
Tokens:119,601
Snippets:1,082
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### setUp() and tearDown() example

Source: https://pub.dev/documentation/test/latest/index.html

Shows how to share setup and cleanup code between tests using setUp() and tearDown(). The setUp() callback runs before every test, and tearDown() runs after, even if a test fails. The example sets up an HttpServer and cleans it up.

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

void main() {
  late HttpServer server;
  late Uri url;
  setUp(() async {
    server = await HttpServer.bind('localhost', 0);
    url = Uri.parse('http://${server.address.host}:${server.port}');
  });

  tearDown(() async {
    await server.close(force: true);
    server = null;
    url = null;
  });

  // ...
}
```

--------------------------------

### Matching examples for equalsIgnoringWhitespace

Source: https://pub.dev/documentation/test/latest/test/equalsIgnoringWhitespace.html

These examples show strings that match the matcher because they are equal to 'hello world' after collapsing whitespace runs and trimming edges.

```dart
expect("hello   world", equalsIgnoringWhitespace("hello world"));
expect("  hello world", equalsIgnoringWhitespace("hello world"));
expect("hello world  ", equalsIgnoringWhitespace("hello world"));
```

--------------------------------

### dart_test.yaml configuration example

Source: https://pub.dev/documentation/test/latest/index.html

Example dart_test.yaml file that sets a global timeout and default platform. These defaults can be overridden by command-line arguments.

```yaml
# This package's tests are very slow. Double the default timeout.
timeout: 2x

# This is a browser-only package, so test on chrome by default.
platforms: [chrome]
```

--------------------------------

### Non-matching examples for equalsIgnoringWhitespace

Source: https://pub.dev/documentation/test/latest/test/equalsIgnoringWhitespace.html

These examples show strings that do not match because they are not equal to 'hello world' even after whitespace normalization.

```dart
expect("helloworld", equalsIgnoringWhitespace("hello world"));
expect("he llo world", equalsIgnoringWhitespace("hello world"));
```

--------------------------------

### setUp

Source: https://pub.dev/documentation/test/latest/scaffolding/

Registers a function to be run before tests.

```APIDOC
## setUp

### Description
Registers a function to be run before tests.

### Method
Function

### Signature
`void setUp(FutureOr callback())`

### Parameters
- **callback** (FutureOr) - Required - The function to be run before tests.

### Returns
void
```

--------------------------------

### Basic test() example

Source: https://pub.dev/documentation/test/latest/index.html

Shows how to define individual tests with test() and make assertions using expect() from package:matcher. The example tests String.split() and String.trim().

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

void main() {
  test('String.split() splits the string on the delimiter', () {
    var string = 'foo,bar,baz';
    expect(string.split(','), equals(['foo', 'bar', 'baz']));
  });

  test('String.trim() removes surrounding whitespace', () {
    var string = '  foo ';
    expect(string.trim(), equals('foo'));
  });
}
```

--------------------------------

### Hybrid test example: WebSocket server and browser test

Source: https://pub.dev/documentation/test/latest/index.html

This example shows a hybrid test setup with a VM-side WebSocket server (web_socket_server.dart) and a browser-side test (web_socket_test.dart). The server uses spawnHybridUri() to load and communicates via a StreamChannel. Requires a dependency on the stream_channel package.

```dart
// ## test/web_socket_server.dart

// The library loaded by spawnHybridUri() can import any packages that your
// package depends on, including those that only work on the VM.
import 'package:shelf/shelf_io.dart' as io;
import 'package:shelf_web_socket/shelf_web_socket.dart';
import 'package:stream_channel/stream_channel.dart';

// Once the hybrid isolate starts, it will call the special function
// hybridMain() with a StreamChannel that's connected to the channel
// returned spawnHybridCode().
hybridMain(StreamChannel channel) async {
  // Start a WebSocket server that just sends "hello!" to its clients.
  var server = await io.serve(webSocketHandler((webSocket, _) {
    webSocket.sink.add('hello!');
  }), 'localhost', 0);

  // Send the port number of the WebSocket server to the browser test, so
  // it knows what to connect to.
  channel.sink.add(server.port);
}

```

```dart
// ## test/web_socket_test.dart

@TestOn('browser')

import 'dart:html';

import 'package:test/test.dart';

void main() {
  test('connects to a server-side WebSocket', () async {
    // Each spawnHybrid function returns a StreamChannel that communicates with
    // the hybrid isolate. You can close this channel to kill the isolate.
    var channel = spawnHybridUri('web_socket_server.dart');

    // Get the port for the WebSocket server from the hybrid isolate.
    var port = await channel.stream.first;

    var socket = WebSocket('ws://localhost:$port');
    var message = await socket.onMessage.first;
    expect(message.data, equals('hello!'));
  });
}

```

--------------------------------

### Example of using onPlatform in test

Source: https://pub.dev/documentation/test/latest/test/test.html

Shows how to use the `onPlatform` parameter to apply platform-specific annotations like `Timeout` and `Skip` to a test. The example demonstrates a test that is slow on Windows and skipped on browsers.

```dart
test('potentially slow test', () {
  // ...
}, onPlatform: {
  // This test is especially slow on Windows.
  'windows': Timeout.factor(2),
  'browser': [
    Skip('TODO: add browser support'),
    // This will be slow on browsers once it works on them.
    Timeout.factor(2)
  ]
});
```

--------------------------------

### Example: group with onPlatform parameter

Source: https://pub.dev/documentation/test/latest/test/group.html

Shows how to use the `onPlatform` parameter to apply platform-specific annotations like `Timeout.factor` and `Skip` to a group of tests. The example includes a comment explaining that tests are especially slow on Windows and a TODO for browser support.

```dart
group('potentially slow tests', () {
  // ...
}, onPlatform: {
  // These tests are especially slow on Windows.
  'windows': Timeout.factor(2),
  'browser': [
    Skip('TODO: add browser support'),
    // They'll be slow on browsers once it works on them.
    Timeout.factor(2)
  ]
});
```

--------------------------------

### setUpAll implementation

Source: https://pub.dev/documentation/test/latest/test/setUpAll.html

The implementation of setUpAll, which delegates to _declarer.setUpAll with the provided callback and optional location. The callback may be asynchronous and must return a Future if so. It runs once before all tests in the group, after parent setUpAll callbacks, and is skipped if no tests in the group run. Prefer setUp over setUpAll to avoid hidden dependencies between tests.

```dart
void setUpAll(
  FutureOr<dynamic> Function() callback, {
  TestLocation? location,
}) => _declarer.setUpAll(callback, location: location);
```

--------------------------------

### group() example

Source: https://pub.dev/documentation/test/latest/index.html

Shows how to group related tests using group(). Each group's description is added to the beginning of its test's descriptions. The example groups tests for String and int types.

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

void main() {
  group('String', () {
    test('.split() splits the string on the delimiter', () {
      var string = 'foo,bar,baz';
      expect(string.split(','), equals(['foo', 'bar', 'baz']));
    });

    test('.trim() removes surrounding whitespace', () {
      var string = '  foo ';
      expect(string.trim(), equals('foo'));
    });
  });

  group('int', () {
    test('.remainder() returns the remainder of division', () {
      expect(11.remainder(3), equals(2));
    });

    test('.toRadixString() returns a hex string', () {
      expect(11.toRadixString(16), equals('b'));
    });
  });
}
```

--------------------------------

### setUp(FutureOr<dynamic> Function() callback)

Source: https://pub.dev/documentation/test/latest/test/setUp.html

Registers a function to be run before each test. The callback may be asynchronous and must return a Future if so. It applies to the current test group or top level.

```APIDOC
## setUp(FutureOr<dynamic> Function() callback)

### Description
Registers a function to be run before tests. This function will be called before each test is run. `callback` may be asynchronous; if so, it must return a `Future`. If called within a test group, it applies only to tests in that group. `callback` will be run after any set-up callbacks in parent groups or at the top level. Each callback at the top level or in a given group will be run in the order they were declared.

### Method
Function

### Signature
```dart
void setUp(FutureOr<dynamic> Function() callback)
```

### Parameters
- **callback** (FutureOr<dynamic> Function()) - Required - The function to be run before each test. May be asynchronous; if so, it must return a Future.

### Implementation
```dart
void setUp(FutureOr<dynamic> Function() callback) => _declarer.setUp(callback);
```

```

--------------------------------

### startsWith

Source: https://pub.dev/documentation/test/latest/expect/

Returns a matcher that matches if the match argument is a string and starts with the given prefix.

```APIDOC
## startsWith

### Description
Returns a matcher that matches if the match argument is a string and starts with `prefixString`.

### Signature
`Matcher startsWith(String prefixString)`

### Parameters
- **prefixString** (String) - The prefix to check for.

### Returns
- **Matcher** - A matcher that checks string prefix.
```

--------------------------------

### Usage example of isA<T>

Source: https://pub.dev/documentation/test/latest/test/isA.html

Shows how to use isA<Duration>() with expect() to verify that a value is of type Duration.

```dart
expect(shouldBeDuration, isA<Duration>());
```

--------------------------------

### startsWith function implementation

Source: https://pub.dev/documentation/test/latest/test/startsWith.html

Returns a matcher that matches if the match argument is a string and starts with the given prefixString. The implementation delegates to _StringStartsWith.

```dart
Matcher startsWith(String prefixString) => _StringStartsWith(prefixString);
```

--------------------------------

### Examples of using throwsA matcher

Source: https://pub.dev/documentation/test/latest/test/throwsA.html

Shows how to use throwsA to match functions that throw, functions with arguments wrapped in a zero-argument closure, and async functions or futures that complete with an exception. Note that for futures, the expectation is asynchronous and expectLater is used.

```dart
void functionThatThrows() => throw SomeException();

void functionWithArgument(bool shouldThrow) {
  if (shouldThrow) {
    throw SomeException();
  }
}

Future<void> asyncFunctionThatThrows() async => throw SomeException();

expect(functionThatThrows, throwsA(isA<SomeException>()));

expect(() => functionWithArgument(true), throwsA(isA<SomeException>()));

var future = asyncFunctionThatThrows();
await expectLater(future, throwsA(isA<SomeException>()));

await expectLater(
    asyncFunctionThatThrows, throwsA(isA<SomeException>()));
```

--------------------------------

### Example use of Fake class with FakeCat

Source: https://pub.dev/documentation/test/latest/fake/Fake-class.html

Shows how to create a fake class by extending Fake and implementing an interface. The FakeCat overrides the meow method, while hiss remains unimplemented and throws UnimplementedError when called. The main function demonstrates calling the overridden method and the throwing behavior.

```dart
// Real class.
class Cat {
  String meow(String suffix) => 'Meow$suffix';
  String hiss(String suffix) => 'Hiss$suffix';
}

// Fake class.
class FakeCat extends Fake implements Cat {
  @override
  String meow(String suffix) => 'FakeMeow$suffix';
}

void main() {
  // Create a new fake Cat at runtime.
  var cat = new FakeCat();

  // Try making a Cat sound...
  print(cat.meow('foo')); // Prints 'FakeMeowfoo'
  print(cat.hiss('foo')); // Throws
}
```

--------------------------------

### addAll(String start, String separator, String end, Iterable list) → Description

Source: https://pub.dev/documentation/test/latest/test/Description-class.html

Adds a description of an Iterable `list`, with appropriate `start` and `end` markers and inter-element `separator`. Returns the Description object for chaining.

```APIDOC
## addAll(String start, String separator, String end, Iterable list) → Description

### Description
Adds a description of an Iterable `list`, with appropriate `start` and `end` markers and inter-element `separator`. Returns the Description object for chaining.

### Method
addAll

### Parameters
- **start** (String) - Required - The start marker.
- **separator** (String) - Required - The separator between elements.
- **end** (String) - Required - The end marker.
- **list** (Iterable) - Required - The iterable to describe.

### Returns
Description - The updated Description object.

```

--------------------------------

### Example usage of predicate<T>

Source: https://pub.dev/documentation/test/latest/test/predicate.html

Shows how to use predicate<num> to check if a value is even. The description 'is even' is provided as the second argument.

```dart
expect(actual, predicate<num>((v) => (v % 2) == 0, 'is even'));
```

--------------------------------

### toString() → String

Source: https://pub.dev/documentation/test/latest/test/StringDescription-class.html

Get the description as a string.

```APIDOC
## toString() → String

### Description
Get the description as a string.

### Method
toString() → String

### Returns
- **String** - The description as a string.

```

--------------------------------

### setUpAll

Source: https://pub.dev/documentation/test/latest/scaffolding/

Registers a function to be run once before all tests.

```APIDOC
## setUpAll

### Description
Registers a function to be run once before all tests.

### Method
Function

### Signature
`void setUpAll(FutureOr callback(), {TestLocation? location})`

### Parameters
- **callback** (FutureOr) - Required - The function to be run once before all tests.
- **location** (TestLocation?) - Optional - The location of the setup.

### Returns
void
```

--------------------------------

### StringDescription([String init = ''])

Source: https://pub.dev/documentation/test/latest/test/StringDescription-class.html

Initialize the description with initial contents `init`.

```APIDOC
## StringDescription([String init = ''])

### Description
Initialize the description with initial contents `init`.

### Constructor
StringDescription([String init = ''])

### Parameters
- **init** (String) - Optional - Initial contents for the description. Defaults to ''.

```

--------------------------------

### internalBootstrapNativeTest(Function getMain(), List<String> args) → void

Source: https://pub.dev/documentation/test/latest/bootstrap_vm/

Bootstraps a native executable test to communicate with the test runner over a socket. This function is called internally to set up the test environment.

```APIDOC
## internalBootstrapNativeTest(Function getMain(), List<String> args) → void

### Description
Bootstraps a native executable test to communicate with the test runner over a socket.

### Method
Function

### Signature
internalBootstrapNativeTest(Function getMain(), List<String> args) → void

### Parameters
- **getMain** (Function) - Required - A function that returns the main test function.
- **args** (List<String>) - Required - List of command-line arguments passed to the test.

### Returns
void
```

--------------------------------

### tags property

Source: https://pub.dev/documentation/test/latest/test/Tags-class.html

Gets the set of tags for the test suite. This property is read-only and has no setter.

```APIDOC
## tags → Set<String>

### Description
The tags for the test suite.

### Property
`Set<String> get tags`

### Returns
- `Set<String>` - The set of tags.
```

--------------------------------

### internalBootstrapVmTest implementation

Source: https://pub.dev/documentation/test/latest/bootstrap_vm/internalBootstrapVmTest.html

Bootstraps a VM test by creating a MultiChannel over an IsolateChannel, piping the serialized suite, and handling debug messages from the test runner.

```dart
void internalBootstrapVmTest(Function Function() getMain, SendPort sendPort) {
  var platformChannel = MultiChannel<Object?>(
    IsolateChannel<Object?>.connectSend(sendPort),
  );
  var testControlChannel = platformChannel.virtualChannel()
    ..pipe(serializeSuite(getMain));
  platformChannel.sink.add(testControlChannel.id);

  platformChannel.stream.forEach((message) {
    assert(message == 'debug');
    debugger(message: 'Paused by test runner');
    platformChannel.sink.add('done');
  });
}
```

--------------------------------

### TypeMatcher with having to validate attributes

Source: https://pub.dev/documentation/test/latest/test/TypeMatcher-class.html

Defines a function that throws a RangeError, then uses TypeMatcher<RangeError>() with chained having calls to verify the start and end properties of the error.

```dart
void shouldThrowRangeError(int value) {
  throw RangeError.range(value, 10, 20);
}

expect(
    () => shouldThrowRangeError(5),
    throwsA(const TypeMatcher<RangeError>()
        .having((e) => e.start, 'start', greaterThanOrEqualTo(10))
        .having((e) => e.end, 'end', lessThanOrEqualTo(20))));
```

--------------------------------

### TestOn annotation with platform selector

Source: https://pub.dev/documentation/test/latest/index.html

Use @TestOn with boolean selector syntax to restrict tests to specific platforms. Example: run on every browser except Chrome when compiled with dart2js.

```dart
@TestOn('browser && !chrome && dart2js')
```

--------------------------------

### internalBootstrapVmTest(Function getMain(), SendPort sendPort) → void

Source: https://pub.dev/documentation/test/latest/bootstrap_vm/

Bootstraps a VM test to communicate with the test runner over an isolate. This function is called internally to set up the test environment.

```APIDOC
## internalBootstrapVmTest(Function getMain(), SendPort sendPort) → void

### Description
Bootstraps a vm test to communicate with the test runner over an isolate.

### Method
Function

### Signature
internalBootstrapVmTest(Function getMain(), SendPort sendPort) → void

### Parameters
- **getMain** (Function) - Required - A function that returns the main test function.
- **sendPort** (SendPort) - Required - The SendPort used for communication with the test runner.

### Returns
void
```

--------------------------------

### Choose compiler with -c flag

Source: https://pub.dev/documentation/test/latest/index.html

Use `dart test -c source` to run all VM tests from source instead of compiling to kernel. Also supports targeting a specific platform, e.g., `dart test -c vm:source`.

```bash
dart test -c source
```

```bash
dart test -c vm:source
```

--------------------------------

### Example hybridMain function for spawnHybridCode

Source: https://pub.dev/documentation/test/latest/test/spawnHybridCode.html

The dartCode passed to spawnHybridCode must define a top-level hybridMain() function that takes a StreamChannel argument and optionally an Object argument for the message. The message must be JSON-encodable.

```dart
import "package:stream_channel/stream_channel.dart";

hybridMain(StreamChannel channel, Object message) {
  // ...
}
```

--------------------------------

### Run tests in Chrome browser

Source: https://pub.dev/documentation/test/latest/index.html

Use `dart test -p chrome path/to/test.dart` to run tests in the Chrome browser. The test runner starts the browser and reports results on the command line.

```bash
dart test -p chrome path/to/test.dart
```

--------------------------------

### Custom HTML file for a browser test (custom_html_test.html)

Source: https://pub.dev/documentation/test/latest/index.html

Create an HTML file with the same name as the test (replacing .dart with .html). It must include a link tag with rel="x-dart-test" and href pointing to the test script, plus <script src="packages/test/dart.js"></script>.

```html
<!doctype html>
<!-- custom_html_test.html -->
<html>
  <head>
    <title>Custom HTML Test</title>
    <link rel="x-dart-test" href="custom_html_test.dart">
    <script src="packages/test/dart.js"></script>
  </head>
  <body>
    // ...
  </body>
</html>
```

--------------------------------

### test()

Source: https://pub.dev/documentation/test/latest/test/anything-constant.html

Creates a new test case with the given description and body. The body is executed when the test runs.

```APIDOC
## test()

### Description
Creates a new test case with the given description and body. The body is executed when the test runs.

### Function Signature
`void test(String description, dynamic Function() body)`

### Parameters
- **description** (String) - Required - The name of the test.
- **body** (Function) - Required - The test body to execute.

### Usage Example
```dart
test('addition', () {
  expect(1 + 1, 2);
});
```
```

--------------------------------

### Run tests on multiple platforms

Source: https://pub.dev/documentation/test/latest/index.html

Use `dart test -p "chrome,vm" path/to/test.dart` to run tests on both Chrome and the Dart VM in a single command.

```bash
dart test -p "chrome,vm" path/to/test.dart
```

--------------------------------

### Description()

Source: https://pub.dev/documentation/test/latest/test/Description-class.html

Constructs a Description object. This is an abstract class and cannot be directly constructed.

```APIDOC
## Description()

### Description
Constructs a Description object. This is an abstract class and cannot be directly constructed.

### Method
Constructor

### Signature
Description()

```

--------------------------------

### Run a test on the Dart VM only

Source: https://pub.dev/documentation/test/latest/index.html

Invoke a test file directly with `dart path/to/test.dart` to run it on the Dart VM without the full test runner, which may lack some features.

```bash
dart path/to/test.dart
```

--------------------------------

### completion

Source: https://pub.dev/documentation/test/latest/test/Func0.html

A matcher for asynchronous completion.

```APIDOC
## completion

### Description
A matcher for asynchronous completion.

### Type
Function

### Usage
Use this function to create a matcher for asynchronous completion.
```

--------------------------------

### internalBootstrapNativeTest implementation

Source: https://pub.dev/documentation/test/latest/bootstrap_vm/internalBootstrapNativeTest.html

Bootstraps a native executable test by connecting to a Unix socket, creating a platform channel, and handling debugger messages. Throws a StateError if the args length is not 1.

```dart
void internalBootstrapNativeTest(
  Function Function() getMain,
  List<String> args,
) async {
  if (args.length != 1) {
    throw StateError('Expected a socket path, but got $args');
  }
  var socket = await Socket.connect(
    InternetAddress(args[0], type: InternetAddressType.unix),
    0,
  );
  var platformChannel = MultiChannel<Object?>(jsonSocketStreamChannel(socket));
  var testControlChannel = platformChannel.virtualChannel()
    ..pipe(serializeSuite(getMain));
  platformChannel.sink.add(testControlChannel.id);

  unawaited(
    platformChannel.stream.forEach((message) {
      assert(message == 'debug');
      debugger(message: 'Paused by test runner');
      platformChannel.sink.add('done');
    }),
  );
}
```

--------------------------------

### expect(actual, matcher, {reason, skip, verbose, formatter})

Source: https://pub.dev/documentation/test/latest/test/expect.html

Assert that `actual` matches `matcher`. This is the main assertion function. `reason` is optional and is typically not supplied, as a reason is generated from `matcher`; if `reason` is included it is appended to the reason generated by the matcher. `matcher` can be a value in which case it will be wrapped in an equals matcher. If the assertion fails a TestFailure is thrown. If `skip` is a String or `true`, the assertion is skipped. The arguments are still evaluated, but `actual` is not verified to match `matcher`. If `actual` is a Future, the test won't complete until the future emits a value. If `skip` is a string, it should explain why the assertion is skipped; this reason will be printed when running the test. Certain matchers, like completion and throwsA, either match or fail asynchronously. When you use expect with these matchers, it ensures that the test doesn't complete until the matcher has either matched or failed. If you want to wait for the matcher to complete before continuing the test, you can call expectLater instead and await the result.

```APIDOC
## expect(actual, matcher, {reason, skip, verbose, formatter})

### Description
Assert that `actual` matches `matcher`. This is the main assertion function. `reason` is optional and is typically not supplied, as a reason is generated from `matcher`; if `reason` is included it is appended to the reason generated by the matcher. `matcher` can be a value in which case it will be wrapped in an equals matcher. If the assertion fails a TestFailure is thrown. If `skip` is a String or `true`, the assertion is skipped. The arguments are still evaluated, but `actual` is not verified to match `matcher`. If `actual` is a Future, the test won't complete until the future emits a value. If `skip` is a string, it should explain why the assertion is skipped; this reason will be printed when running the test. Certain matchers, like completion and throwsA, either match or fail asynchronously. When you use expect with these matchers, it ensures that the test doesn't complete until the matcher has either matched or failed. If you want to wait for the matcher to complete before continuing the test, you can call expectLater instead and await the result.

### Method
Function

### Signature
```dart
void expect(
  dynamic actual,
  dynamic matcher, {
  String? reason,
  Object? /* String|bool */ skip,
  @Deprecated('Will be removed in 0.13.0.') bool verbose = false,
  @Deprecated('Will be removed in 0.13.0.') ErrorFormatter? formatter,
})
```

### Parameters
#### Positional Parameters
- **actual** (dynamic) - Required - The value to be tested.
- **matcher** (dynamic) - Required - The matcher to test `actual` against. Can be a value, in which case it is wrapped in an equals matcher.

#### Named Parameters
- **reason** (String?) - Optional - An optional reason to append to the reason generated by the matcher.
- **skip** (Object?) - Optional - If a String or `true`, the assertion is skipped. The arguments are still evaluated, but `actual` is not verified to match `matcher`. If a string, it should explain why the assertion is skipped.
- **verbose** (bool) - Optional - Deprecated. Will be removed in 0.13.0. Defaults to `false`.
- **formatter** (ErrorFormatter?) - Optional - Deprecated. Will be removed in 0.13.0.

### Behavior
- If the assertion fails, a TestFailure is thrown.
- If `skip` is a String or `true`, the assertion is skipped. The arguments are still evaluated, but `actual` is not verified to match `matcher`. If `actual` is a Future, the test won't complete until the future emits a value.
- Certain matchers, like completion and throwsA, either match or fail asynchronously. When you use expect with these matchers, it ensures that the test doesn't complete until the matcher has either matched or failed. If you want to wait for the matcher to complete before continuing the test, you can call expectLater instead and await the result.

### Implementation
```dart
void expect(
  dynamic actual,
  dynamic matcher, {
  String? reason,
  Object? /* String|bool */ skip,
  @Deprecated('Will be removed in 0.13.0.') bool verbose = false,
  @Deprecated('Will be removed in 0.13.0.') ErrorFormatter? formatter,
}) {
  _expect(
    actual,
    matcher,
    reason: reason,
    skip: skip,
    verbose: verbose,
    formatter: formatter,
  );
}
```
```

--------------------------------

### test

Source: https://pub.dev/documentation/test/latest/scaffolding/

Creates a new test case with the given description (converted to a string) and body. Supports various options for platform, timeout, skipping, tags, and retries.

```APIDOC
## test

### Description
Creates a new test case with the given description (converted to a string) and body. Supports various options for platform, timeout, skipping, tags, and retries.

### Method
Function

### Signature
void test(Object? description, FutureOr<void> Function() body, {String? testOn, Timeout? timeout, Object? skip, Object? tags, Map<String, dynamic>? onPlatform, int? retry, TestLocation? location, bool solo = false})

### Parameters
- **description** (Object?) - Required - The description of the test case, converted to a string.
- **body** (FutureOr<void> Function()) - Required - The test body function.
- **testOn** (String?) - Optional - A platform selector specifying on which platforms the test should run.
- **timeout** (Timeout?) - Optional - The timeout for the test.
- **skip** (Object?) - Optional - Whether to skip the test, can be a bool or a string reason.
- **tags** (Object?) - Optional - Tags for the test.
- **onPlatform** (Map<String, dynamic>?) - Optional - Platform-specific overrides.
- **retry** (int?) - Optional - Number of retries for the test.
- **location** (TestLocation?) - Optional - The location of the test declaration.
- **solo** (bool) - Optional - Whether the test should be run in solo mode. Defaults to false.
```

--------------------------------

### Functions

Source: https://pub.dev/documentation/test/latest/test/everyElement.html

Functions for creating matchers, registering cleanup, and asserting expectations.

```APIDOC
## Functions

### Description
These functions provide matchers, test utilities, and assertion helpers.

### Functions
- **addStateInfo** - Adds state information to a test.
- **addTearDown** - Registers a tear-down callback.
- **allOf** - Combines multiple matchers with logical AND.
- **anyElement** - Matcher that checks if any element satisfies a matcher.
- **anyOf** - Combines multiple matchers with logical OR.
- **closeTo** - Matcher for numeric closeness.
- **collapseWhitespace** - Matcher that collapses whitespace in strings.
- **completion** - Matcher for Future completion.
- **contains** - Matcher for substring containment.
- **containsAll** - Matcher for collection containment.
- **containsAllInOrder** - Matcher for ordered collection containment.
- **containsOnce** - Matcher for single occurrence.
- **containsPair** - Matcher for map key-value pairs.
- **containsValue** - Matcher for map values.
- **emits** - Matcher for stream emissions.
- **emitsAnyOf** - Matcher for any of multiple emissions.
- **emitsError** - Matcher for stream errors.
- **emitsInAnyOrder** - Matcher for emissions in any order.
- **emitsInOrder** - Matcher for emissions in order.
- **emitsThrough** - Matcher for stream completion.
- **endsWith** - Matcher for string suffix.
- **equals** - Matcher for equality.
- **equalsIgnoringCase** - Matcher for case-insensitive equality.
- **equalsIgnoringWhitespace** - Matcher for whitespace-insensitive equality.
- **escape** - Escapes a string for use in matchers.
- **everyElement** - Matcher that checks if every element satisfies a matcher.
- **expect** - Asserts that a value satisfies a matcher.
- **expectAsync** - Wraps a callback to count invocations.
- **expectAsync0** through **expectAsync6** - Variants for different arities.
- **expectAsyncUntil0** through **expectAsyncUntil3** - Variants with a stop condition.
```

--------------------------------

### Functions

Source: https://pub.dev/documentation/test/latest/test/isStateError-constant.html

Functions for setting up tests, adding teardown, and asserting expectations.

```APIDOC
## Functions

### Description
These functions are used to set up tests, add teardown logic, and assert expectations.

### Functions
- `addStateInfo(info)` - Adds state information to the current test.
- `addTearDown(callback)` - Registers a callback to run after the test.
- `expect(actual, matcher)` - Asserts that the actual value matches the given matcher.
- `expectAsync(callback)` - Wraps a callback to verify it is called asynchronously.
- `expectAsync0(callback)` - Wraps a zero-argument callback.
- `expectAsync1(callback)` - Wraps a one-argument callback.
- `expectAsync2(callback)` - Wraps a two-argument callback.
- `expectAsync3(callback)` - Wraps a three-argument callback.
- `expectAsync4(callback)` - Wraps a four-argument callback.
- `expectAsync5(callback)` - Wraps a five-argument callback.
- `expectAsync6(callback)` - Wraps a six-argument callback.
- `expectAsyncUntil0(callback, condition)` - Wraps a zero-argument callback until a condition is met.
- `expectAsyncUntil1(callback, condition)` - Wraps a one-argument callback until a condition is met.
- `expectAsyncUntil2(callback, condition)` - Wraps a two-argument callback until a condition is met.
- `expectAsyncUntil3(callback, condition)` - Wraps a three-argument callback until a condition is met.
- `expectAsyncUntil4(callback, condition)` - Wraps a four-argument callback until a condition is met.
- `setUp(callback)` - Registers a callback to run before each test.
- `tearDown(callback)` - Registers a callback to run after each test.
- `test(description, body)` - Defines a test case.
- `group(description, body)` - Defines a group of tests.

### Usage
These functions are used to structure and assert tests in the Dart test framework.
```

--------------------------------

### expect(dynamic actual, dynamic matcher, {String? reason, Object? skip, bool verbose = false, ErrorFormatter? formatter}) → void

Source: https://pub.dev/documentation/test/latest/expect/

Assert that `actual` matches `matcher`.

```APIDOC
## expect(dynamic actual, dynamic matcher, {String? reason, Object? skip, bool verbose = false, ErrorFormatter? formatter}) → void

### Description
Assert that `actual` matches `matcher`.

### Parameters
- **actual** (dynamic) - Required - The value to test.
- **matcher** (dynamic) - Required - The matcher to use.
- **reason** (String?) - Optional - A description of the assertion.
- **skip** (Object?) - Optional - If provided, the assertion is skipped.
- **verbose** (bool) - Optional - Whether to print verbose output. Defaults to false.
- **formatter** (ErrorFormatter?) - Optional - Custom error formatter.

### Returns
- **void**
```

--------------------------------

### Run Dart tests with coverage and generate report

Source: https://pub.dev/documentation/test/latest/index.html

Run Dart tests with --coverage-path to output LCOV coverage to ./coverage/lcov.info, then generate a human-readable report with genhtml and open it. Coverage is only implemented for tests run on the Dart VM or Chrome.

```shell
## Run Dart tests and output coverage info to `./coverage/lcov.info`:
dart run test --coverage-path=./coverage/lcov.info

## Generate a human readable report:
genhtml -o ./coverage/report ./coverage/lcov.info

## Open the coverage report:
open ./coverage/report/index.html
```

--------------------------------

### wrapMatcher

Source: https://pub.dev/documentation/test/latest/expect/

Takes an argument and returns an equivalent Matcher.

```APIDOC
## wrapMatcher

### Description
Takes an argument and returns an equivalent [Matcher].

### Signature
`Matcher wrapMatcher(Object? valueOrMatcher)`

### Parameters
- **valueOrMatcher** (Object?) - The value or matcher to wrap.

### Returns
- **Matcher** - An equivalent matcher.
```

--------------------------------

### matchQueue method

Source: https://pub.dev/documentation/test/latest/test/StreamMatcher-class.html

Tries to match events emitted by `queue`. Returns a Future that completes with a description of the mismatch, or null if the match succeeds.

```APIDOC
## matchQueue(StreamQueue queue)

### Description
Tries to match events emitted by `queue`.

### Method
Future<String?> matchQueue(StreamQueue queue)

### Parameters
- **queue** (StreamQueue) - Required - The stream queue to match events from.

### Returns
Future<String?> - A Future that completes with a description of the mismatch, or null if the match succeeds.
```

--------------------------------

### completion(Object? matcher, [String? description]) → Matcher

Source: https://pub.dev/documentation/test/latest/test/

Matches a Future that completes successfully with a value that matches matcher.

```APIDOC
## completion(Object? matcher, [String? description]) → Matcher

### Description
Matches a Future that completes successfully with a value that matches matcher.

### Signature
`Matcher completion(Object? matcher, [String? description])`

### Parameters
- **matcher** (Object?) - Required - The matcher to apply to the future's value.
- **description** (String?) - Optional - A description of the matcher.

### Returns
Matcher
```

--------------------------------

### describe

Source: https://pub.dev/documentation/test/latest/test/CustomMatcher-class.html

Builds a textual description of the matcher.

```APIDOC
## describe(Description description) → Description

### Description
Builds a textual description of the matcher, including the feature description and the matcher's description.

### Parameters
- **description** (Description) - Required - The description object to append to.

### Returns
- **Description** - The updated description.
```

--------------------------------

### TestLocation constructor

Source: https://pub.dev/documentation/test/latest/test/TestLocation-class.html

Creates a new TestLocation instance with the given URI, line, and column.

```APIDOC
## TestLocation(Uri uri, int line, int column)

### Description
Creates a new TestLocation instance with the given URI, line, and column.

### Parameters
- **uri** (Uri) - Required - The URI of the test or group.
- **line** (int) - Required - The line number of the test or group.
- **column** (int) - Required - The column number of the test or group.

### Returns
A new TestLocation instance.
```

--------------------------------

### Functions

Source: https://pub.dev/documentation/test/latest/test/endsWith.html

Functions for setting up tests, making assertions, and handling asynchronous operations.

```APIDOC
## Functions

### Description
Functions for setting up tests, making assertions, and handling asynchronous operations.

### List of Functions
- `expect` - Asserts that a value matches a matcher.
- `expectAsync` - Wraps a callback to verify it is called a certain number of times.
- `expectAsync0` through `expectAsync6` - Variants of `expectAsync` for callbacks with 0 to 6 arguments.
- `expectAsyncUntil0` through `expectAsyncUntil4` - Variants of `expectAsync` with a condition to stop expecting.
- `addTearDown` - Registers a callback to run after the test.
- `addStateInfo` - Adds state information to the test.
- `setUp` - Registers a function to run before each test.
- `tearDown` - Registers a function to run after each test.
- `test` - Defines a test case.
- `group` - Groups test cases.
- `fail` - Fails the test with a message.
- `markTestSkipped` - Marks the test as skipped.
- `printOnFailure` - Prints a message if the test fails.
- `expectLater` - Asserts that a Future completes with a matcher.
- `expectAsyncUntil` - Variant of `expectAsync` with a condition.
- `completes` - Matcher for a Future that completes successfully.
- `doesNotComplete` - Matcher for a Future that does not complete.
- `neverCalled` - Matcher for a callback that should never be called.

### Usage
Functions are used to define and control test behavior.

### Example
```dart
test('addition', () {
  expect(2 + 2, equals(4));
});
```
```

--------------------------------

### StreamMatcher constructor

Source: https://pub.dev/documentation/test/latest/test/StreamMatcher-class.html

Creates a new StreamMatcher described by `description` that matches events with `matchQueue`.

```APIDOC
## StreamMatcher(StreamMatcher matchQueue, String description)

### Description
Creates a new StreamMatcher described by `description` that matches events with `matchQueue`.

### Constructor
StreamMatcher(Future<String?> Function(StreamQueue) matchQueue, String description)

### Parameters
- **matchQueue** (Function) - Required - A function that takes a StreamQueue and returns a Future<String?> indicating match result.
- **description** (String) - Required - The description of this matcher.

### Returns
A new StreamMatcher instance.
```

--------------------------------

### internalBootstrapBrowserTest implementation

Source: https://pub.dev/documentation/test/latest/bootstrap_browser/internalBootstrapBrowserTest.html

Bootstraps a browser test by serializing the test suite and piping it to the test channel. It sets up a stack trace mapper from the browser mapper if available.

```dart
void internalBootstrapBrowserTest(
  Function Function() getMain, {
  StreamChannel<Object?>? testChannel,
}) {
  var channel = serializeSuite(
    getMain,
    hidePrints: false,
    beforeLoad: (suiteChannel) async {
      var serialized = await suiteChannel('test.browser.mapper').stream.first;
      if (serialized is! Map) return;
      setStackTraceMapper(JSStackTraceMapper.deserialize(serialized)!);
    },
  );
  (testChannel ?? postMessageChannel()).pipe(channel);
}
```

--------------------------------

### CustomMatcher constructor

Source: https://pub.dev/documentation/test/latest/test/CustomMatcher-class.html

Creates a CustomMatcher with a feature description, feature name, and a value or matcher.

```APIDOC
## CustomMatcher(String _featureDescription, String _featureName, Object? valueOrMatcher)

### Description
Constructs a CustomMatcher instance with the given feature description, feature name, and value or matcher.

### Parameters
- **_featureDescription** (String) - Required - A description of the feature being matched.
- **_featureName** (String) - Required - The name of the feature.
- **valueOrMatcher** (Object?) - Required - The expected value or a matcher for the feature.
```

--------------------------------

### Using StreamMatcher with StreamQueue and expectLater()

Source: https://pub.dev/documentation/test/latest/test/StreamMatcher-class.html

Shows how to use StreamMatcher with a StreamQueue, consuming matched events. The expectLater() call returns a Future that completes when matching is done, allowing interleaving with other operations. Demonstrates matching through a URL, parsing the next line, and matching again on the same queue.

```dart
var stdout = StreamQueue(stdoutLineStream);

// Ignore lines from the process until it's about to emit the URL.
await expectLater(stdout, emitsThrough('WebSocket URL:'));

// Parse the next line as a URL.
var url = Uri.parse(await stdout.next);
expect(url.host, equals('localhost'));

// You can match against the same StreamQueue multiple times.
await expectLater(stdout, emits('Waiting for connection...'));
```

--------------------------------

### same

Source: https://pub.dev/documentation/test/latest/expect/

Returns a matcher that matches if the value is the same instance as expected, using identical.

```APIDOC
## same

### Description
Returns a matches that matches if the value is the same instance as `expected`, using [identical].

### Signature
`Matcher same(Object? expected)`

### Parameters
- **expected** (Object?) - The expected instance.

### Returns
- **Matcher** - A matcher that checks for identical instances.
```

--------------------------------

### Fake()

Source: https://pub.dev/documentation/test/latest/fake/Fake-class.html

Constructs a new Fake instance. This is the default constructor for the Fake class.

```APIDOC
## Fake()

### Description
Constructs a new Fake instance.

### Method
Constructor

### Signature
Fake()

### Usage
```dart
var fake = Fake();
```
```

--------------------------------

### Use HasPrice matcher in an expectation

Source: https://pub.dev/documentation/test/latest/test/CustomMatcher-class.html

Shows how to use the custom matcher with expect to assert that an inventory item has a price greater than 0.

```dart
expect(inventoryItem, HasPrice(greaterThan(0)));
```

--------------------------------

### emitsThrough

Source: https://pub.dev/documentation/test/latest/test/emitsDone.html

Creates a matcher that matches a stream that emits events through a given matcher.

```APIDOC
## emitsThrough

### Description
Creates a matcher that matches a stream that emits events through a given matcher.

### Type
Function
```

--------------------------------

### internalBootstrapNodeTest implementation

Source: https://pub.dev/documentation/test/latest/bootstrap_node/internalBootstrapNodeTest.html

Bootstraps a browser test to communicate with the test runner. It serializes the suite, sets up a stack trace mapper if a serialized map is received, and pipes the socket channel to the suite channel.

```dart
void internalBootstrapNodeTest(Function Function() getMain) {
  var channel = serializeSuite(
    getMain,
    beforeLoad: (suiteChannel) async {
      var serialized = await suiteChannel('test.node.mapper').stream.first;
      if (serialized is! Map) return;
      setStackTraceMapper(JSStackTraceMapper.deserialize(serialized)!);
    },
  );
  socketChannel().then((socket) => socket.pipe(channel));
}
```

--------------------------------

### Target a specific platform with compiler selector

Source: https://pub.dev/documentation/test/latest/

Targets a specific platform using normal platform selectors combined with the compiler flag.

```bash
dart test -c vm:source
```

--------------------------------

### completion

Source: https://pub.dev/documentation/test/latest/test/completion.html

Matches a Future that completes successfully with a value that matches `matcher`. This creates an asynchronous expectation. The call to expect will return immediately and execution will continue. Later, when the future completes, the expectation against `matcher` will run. To wait for the future to complete and the expectation to run use expectLater and wait on the returned future.

```APIDOC
## completion

### Description
Matches a [Future](https://api.dart.dev/stable/3.13.5/dart-async/Future-class.html) that completes successfully with a value that matches `matcher`.

This creates an asynchronous expectation. The call to [expect](https://pub.dev/documentation/test/latest/test/expect.html) will return immediately and execution will continue. Later, when the future completes, the expectation against `matcher` will run. To wait for the future to complete and the expectation to run use [expectLater](https://pub.dev/documentation/test/latest/test/expectLater.html) and wait on the returned future.

To test that a Future completes with an exception, you can use [throws](https://pub.dev/documentation/test/latest/test/throws-constant.html) and [throwsA](https://pub.dev/documentation/test/latest/test/throwsA.html).

### Signature
```dart
Matcher completion(
  Object? matcher, [
  @Deprecated('this parameter is ignored') String? description,
]) => _Completes(wrapMatcher(matcher));
```

### Parameters
- **matcher** (Object?) - Required - The matcher that the future's value must match.
- **description** (String?) - Optional - Deprecated: this parameter is ignored.

### Returns
- **Matcher** - A matcher that matches a Future that completes successfully with a value matching `matcher`.

### Usage
To use this matcher, pass it to `expect` or `expectLater` along with a Future. For example:
```dart
await expectLater(future, completion(equals(42)));
```
```

--------------------------------

### Platform-specific configuration with @OnPlatform and onPlatform

Source: https://pub.dev/documentation/test/latest/index.html

Use @OnPlatform annotation and onPlatform parameter to configure tests differently per platform. The map keys are platform selectors; values can be Skip, Timeout, or a list of these. If multiple platforms match, configuration applies in order from first to last, with the last matching value winning for duration-based timeouts.

```dart
@OnPlatform({
  // Give Windows some extra wiggle-room before timing out.
  'windows': Timeout.factor(2)
})

import 'package:test/test.dart';

void main() {
  test('do a thing', () {
    // ...
  }, onPlatform: {
    'safari': Skip('Safari is currently broken (see #1234)')
  });
}
```
Tokens:
Raw