### Example dart_test.yaml Configuration

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

This example demonstrates setting a doubled default timeout for all tests, specifying Chrome as the default platform, and configuring a specific timeout for integration tests.

```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]

tags:
  # Integration tests are even slower, so increase the timeout again.
  integration: {timeout: 2x}

  # Sanity tests are quick and verify that nothing is obviously wrong. Declaring
  # the tag allows us to tag tests with it without getting warnings.
  sanity:

```

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

### Example Platform Selector Usage

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Demonstrates how to use platform selectors to target specific environments. This example targets all browsers except Chrome when compiled with dart2js.

```dart
browser && !chrome && dart2js
```

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

### Basic Test Example with checks

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/README.md

Demonstrates the basic usage of the `checks` library within a Dart test function. Includes examples of checking equality, non-emptiness, type, and string properties.

```dart
void main() {
  test('sample test', () {
    // test code here
    ...

    check(actual).equals(expected);
    check(someList).isNotEmpty();
    check(someObject).isA<Map>();
    check(someString)..startsWith('a')..endsWith('z')..contains('lmno');
  });
}
```

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

### Select Test Compiler

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Choose the compiler for running tests. For example, to run VM tests from source instead of compiling them to kernel, use `-c vm:source`.

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

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

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

### StartEvent

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

An event emitted at the beginning of the test run, indicating the runner has started.

```APIDOC
## StartEvent

### Description
A single start event is emitted before any other events. It indicates that the test runner has started running.

### Method
N/A (Event)

### Endpoint
N/A (Event)

### Attributes
- **type** (String) - "start"
- **time** (int) - The time (in milliseconds) that has elapsed since the test runner started.
- **protocolVersion** (String) - The version of the JSON reporter protocol being used. This is a semantic version, but it reflects only the version of the protocol—it's not identical to the version of the test runner itself.
- **runnerVersion** (String?) - The version of the test runner being used. This is null if for some reason the version couldn't be loaded.
- **pid** (int) - The pid of the VM process running the tests.
```

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

### Start and interact with a subprocess

Source: https://github.com/dart-lang/test/blob/master/pkgs/test_process/README.md

Starts a subprocess and reads its standard output line by line using a pull-based API. Asserts the process exits with a specific code.

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

void main() {
  test('pub get gets dependencies', () async {
    // TestProcess.start() works just like Process.start() from dart:io.
    var process = await TestProcess.start('dart', ['pub', 'get']);

    // StreamQueue.next returns the next line emitted on standard out.
    var firstLine = await process.stdout.next;
    expect(firstLine, equals('Resolving dependencies...'));

    // Each call to StreamQueue.next moves one line further.
    String next;
    do {
      next = await process.stdout.next;
    } while (next != 'Got dependencies!');

    // Assert that the process exits with code 0.
    await process.shouldExit(0);
  });
}
```

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

### Configure Tags with Timeout

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Applies configuration, such as a timeout, to all tests with a specific tag. This example sets a 1-minute timeout for 'integration' tests.

```yaml
tags:
  integration:
    timeout: 1m
```

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

### Include Base Configuration File

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/package_config.md

Use the `include` field to load another configuration file, useful for sharing configurations across multiple packages in a repository. This example includes a base YAML file.

```yaml
include: ../dart_test_base.yaml
```

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

### Configure OS-Specific Settings

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `on_os` to apply global configuration based on the operating system the test runner is running on. This example sets color to false and runner to expanded for Windows, and concurrency for Linux.

```yaml
on_os:
  windows:
    # Both of these are the defaults anyway, but let's be explicit about it.
    color: false
    runner: expanded

    # My Windows machine is real slow.
    timeout: 2x

  # My Linux machine has SO MUCH RAM.
  linux:
    concurrency: 500
```

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

### Set Up and Tear Down Resources for Dart Tests

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Use `setUp()` to run code before each test and `tearDown()` to run code after each test, even if the test fails. This is useful for resource management. Requires importing `package:test`.

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

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;
  });

  // ...
}
```

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

### Define New Custom Platforms

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `define_platforms` to create new platforms based on existing ones. This example defines a 'chromium' platform that extends 'chrome' and specifies 'chromium' as its executable.

```yaml
define_platforms:
  # This identifier is used to select the platform with the --platform flag.
  chromium:
    # A human-friendly name for the platform.
    name: Chromium

    # The identifier for the platform that this is based on.
    extends: chrome

    # Settings for the new child platform.
    settings:
      executable: chromium
```

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

### Hybrid Isolate Server Setup

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Sets up a WebSocket server within a hybrid isolate. Imports VM-only libraries like 'dart:io'. The hybridMain function receives a StreamChannel to communicate with the browser test.

```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);
}
```

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

### Configure Test Platform-Specific Settings

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `on_platform` to apply configuration to tests running on specific platforms. This example sets a timeout for tests running on Chrome or Safari.

```yaml
# Our code is kind of slow on Blink and WebKit.
on_platform:
  chrome || safari: {timeout: 2x}
```

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

### Set Extra Arguments for Browser Executables

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use the `arguments` setting within `override_platforms` to provide extra command-line arguments to browser executables. This example sets the Firefox executable to run in headless mode.

```yaml
override_platforms:
  firefox:
    settings:
      arguments: -headless
```

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

### Configure Tags with Boolean Selectors

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Applies configuration to tests matching a combination of tags using boolean selector syntax. This example sets a timeout for tests tagged with 'ruby' OR 'python'.

```yaml
tags:
  ruby || python:
    timeout: 1.5x
```

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

### Preset with Skipped Chrome Tests

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Example of a preset that skips Chrome tests due to a known issue, with an option to override the skip.

```yaml
tags:
  chrome:
    skip: "Our Chrome launcher is busted. See issue 1234."

    # Pass -P force to verify that the launcher is still busted.
    presets: {force: {skip: false}}
```

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

### Asynchronous Test Example

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Shows a basic asynchronous test using `async`/`await`. The test runner waits for the returned Future to complete before considering the test finished.

```dart
import 'dart:async';

import 'package:test/test.dart';

void main() {
  test('Future.value() returns the value', () async {
    var value = await Future.value(10);
    expect(value, equals(10));
  });
}
```

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

### Use stream matchers for subprocess output

Source: https://github.com/dart-lang/test/blob/master/pkgs/test_process/README.md

Starts a subprocess and uses test package's stream matchers to assert its standard output. This approach is cleaner for verifying output sequences.

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

void main() {
  test('pub get gets dependencies', () async {
    var process = await TestProcess.start('dart', ['pub', 'get']);

    // Each stream matcher will consume as many lines as it matches from a
    // StreamQueue, and no more, so it's safe to use them in sequence.
    await expectLater(process.stdout, emits('Resolving dependencies...'));

    // The emitsThrough matcher matches and consumes any number of lines, as
    // long as they end with one matching the argument.
    await expectLater(process.stdout, emitsThrough('Got dependencies!'));

    await process.shouldExit(0);
  });
}
```

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

### Specify Default Test Paths

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

The `paths` field indicates the default directories or filenames the test runner should execute. Paths must be relative and in URL format. This example specifies a single directory.

```yaml
paths: [dart/test]
```

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

### Define TestStartEvent for Test Execution Start

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Emitted when a test begins running. This is the only event containing full test metadata; subsequent events use the test ID.

```dart
class TestStartEvent extends Event {
  String type = "testStart";

  // Metadata about the test that started.
  Test test;
}
```

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

### Target Specific Platforms for Tags

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `test_on` with a platform selector to define which platforms tests associated with a tag should run on. This example targets browsers excluding Firefox.

```yaml
tags:
  # Test on browsers other than firefox
  some_feature: {test_on: "browser && !firefox"}
```

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

### Emitting Stream Events in Order

Source: https://github.com/dart-lang/test/blob/master/pkgs/matcher/README.md

Use `emitsInOrder` to assert that a stream emits a sequence of events, including data, matchers, and `emitsDone`. This example demonstrates matching specific strings, a `startsWith` matcher, `emitsAnyOf`, and `emitsDone`.

```dart
import 'dart:async';

import 'package:test/test.dart';

void main() {
  test('process emits status messages', () {
    // Dummy data to mimic something that might be emitted by a process.
    var stdoutLines = Stream.fromIterable([
      'Ready.',
      'Loading took 150ms.',
      'Succeeded!'
    ]);

    expect(stdoutLines, emitsInOrder([
      // Values match individual events.
      'Ready.',

      // Matchers also run against individual events.
      startsWith('Loading took'),

      // Stream matchers can be nested. This asserts that one of two events are
      // emitted after the "Loading took" line.
      emitsAnyOf(['Succeeded!', 'Failed!']),

      // By default, more events are allowed after the matcher finishes
      // matching. This asserts instead that the stream emits a done event and
      // nothing else.
      emitsDone
    ]));
  });
}
```

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

### Retry Failed Tests

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Configure the `retry` field within tags to specify the number of times a test should be retried upon failure. This example retries chrome failures 3 times.

```yaml
tags:
  chrome:
    retry: 3 # Retry chrome failures 3 times.
```

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

### Usage

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Instructions on how to activate and use the JSON reporter.

```APIDOC
## Usage

Pass the `--reporter json` command-line flag to the test runner to activate the JSON reporter.

```bash
dart test --reporter json <path-to-test-file>
```

You may also use the `--file-reporter` option to enable the JSON reporter output to a file, in addition to another reporter writing to stdout.

```bash
dart test --file-reporter json:reports/tests.json <path-to-test-file>
```

The JSON stream will be emitted via standard output. It will be a stream of JSON objects, separated by newlines.
```

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

### Include Base Configuration File

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use the `include` field to load another configuration file, useful for sharing configuration across multiple packages in a repository. Local fields take precedence.

```yaml
# repo/dart_test_base.yaml
filename: "test_*.dart"
```

```yaml
# repo/package/dart_test.yaml
include: ../dart_test_base.yaml
```

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

### Override Built-in Platform Settings

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `override_platforms` to customize settings for built-in test platforms. This example sets the executable for Chrome tests to 'chromium'.

```yaml
override_platforms:
  chrome:
    # The settings to override for this platform.
    settings:
      executable: chromium
```

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

### Exception Type Checking with throws in Dart Test

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/doc/migrating_from_matcher.md

Use 'throws<Type>()' instead of specific exception matchers like 'throwsArgumentError'. For example, 'throws<ArgumentError>'.

```dart
throws<ArgumentError>
```

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

### Type Checking with isA in Dart Test

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/doc/migrating_from_matcher.md

Instead of type-specific matchers like 'isArgumentError', use 'isA<Type>()' for type checking. For example, 'isA<ArgumentError>'.

```dart
isA<ArgumentError>
```

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

### Activate JSON Reporter via Command Line

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Use the `--reporter json` flag to enable the JSON reporter. For file output, use `--file-reporter json:<path-to-file>`.

```bash
dart test --reporter json <path-to-test-file>
```

```bash
dart test --file-reporter json:reports/tests.json <path-to-test-file>
```

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

### Event Base Class Definition

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

The root class for all JSON reporter events. It includes the event type and the time elapsed since the test runner started.

```dart
abstract class Event {
  // The type of the event.
  //
  // This is always one of the subclass types listed below.
  String type;

  // The time (in milliseconds) that has elapsed since the test runner started.
  int time;
}
```

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

### Run Tests by Name

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Select specific tests to run using a regular expression for their description with the `-n` flag, or a plain-text string with the `-N` flag.

```bash
dart test -n "test name"
```

```bash
dart test -N "test name"
```

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

### StartEvent Definition

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Emitted once at the beginning of the test run. Includes protocol version, runner version, and the VM process ID.

```dart
class StartEvent extends Event {
  String type = "start";

  // The version of the JSON reporter protocol being used.
  //
  // This is a semantic version, but it reflects only the version of the
  // protocol—it's not identical to the version of the test runner itself.
  String protocolVersion;

  // The version of the test runner being used.
  //
  // This is null if for some reason the version couldn't be loaded.
  String? runnerVersion;

  // The pid of the VM process running the tests.
  int pid;
}
```

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

### Add Inherited Tags

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Adds additional tags to tests, enabling tag inheritance. This example configures 'chrome', 'firefox', 'safari', and 'edge' tests to also inherit the 'browser' tag.

```yaml
tags:
  browser:
    timeout: 2x

  chrome: {add_tags: [browser]}
  firefox: {add_tags: [browser]}
  safari: {add_tags: [browser]}
  edge: {add_tags: [browser]}
```

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

### Run All Presubmit Checks

Source: https://github.com/dart-lang/test/blob/master/CONTRIBUTING.md

Execute all additional presubmit checks locally using the mono_repo tool. This command should be run from the root of the repository.

```bash
pub global run mono_repo presubmit
```

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

### Set Default Platform for Package

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Configure `test_on` at the top level to specify the platform the entire package supports. The runner will warn and skip unsupported platforms.

```yaml
# This package uses dart:io.
test_on: vm
```

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

### Specify Default Test Platforms

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `platforms` to set the default platforms tests should run on. Defaults to `[vm]`.

```yaml
platforms: [chrome]

platforms:
- chrome
- firefox
```

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

### Define Executable Paths for Platforms

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Specify executable paths for different operating systems. Defaults to using the system's PATH if a platform is omitted.

```yaml
define_platforms:
  chromium:
    name: Chromium
    extends: chrome

    settings:
      executable:
        linux: chromium
        mac_os: /Applications/Chromium.app/Contents/MacOS/Chromium
        windows: Chromium\Application\chrome.exe
```

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

### Set Suite Load Timeout

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Configure the maximum time allowed for compiling and loading a test suite. Use '1m' for one minute.

```yaml
suite_load_timeout: 1m
```

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

### Generate Check Extensions with @CheckExtensions

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks_codegen/README.md

Use the @CheckExtensions annotation in a shared testing library or a specific test suite to generate check extensions for listed types. This example shows how to generate extensions for the TypedData type.

```dart
@CheckExtensions([TypedData])
import 'some_test.checks.dart';

// The `elementSizeInBytes` and `lengthInBytes` extensions are generated.
void main() {
  test('sample test', () {
    check(typedData)
        ..elementSizeInBytes.equals(expectedElementSize)
        ..lengthInBytes.equals(expectedLength);
  });
}
```

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

### Specify Multiple Default Test Paths

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use a list for the `paths` field to specify multiple default directories or filenames for the test runner. Paths must be relative and in URL format.

```yaml
paths:
- test/instantaneous
- test/fast
- test/middling
```

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

### Run a Single Dart Test File

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Execute a specific test file using the `dart test` command. For SDK versions prior to 2.10, use `pub run test` instead.

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

```bash
pub run test
```

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

### AllSuitesEvent

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

An event indicating the total number of suites to be loaded.

```APIDOC
## AllSuitesEvent

### Description
A single suite count event is emitted once the test runner knows the total number of suites that will be loaded over the course of the test run. Because this is determined asynchronously, its position relative to other events (except `StartEvent`) is not guaranteed.

### Method
N/A (Event)

### Endpoint
N/A (Event)

### Attributes
- **type** (String) - "allSuites"
- **time** (int) - The time (in milliseconds) that has elapsed since the test runner started.
- **count** (int) - The total number of suites that will be loaded.
```

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

### Running Tests on Node.js

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Illustrates how to compile and run tests on Node.js using the `--platform node` flag. Tests running on Node.js cannot access `dart:html` or `dart:io` and must use the `js` package for platform-specific APIs.

```dart
const bool.fromEnvironment('node')
```

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

### TestStartEvent

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Indicates that a test has begun running. This event contains the complete metadata for the test, which is referenced by its opaque ID in subsequent events.

```APIDOC
## TestStartEvent

### Description
An event emitted when a test begins running. This is the only event that contains the full metadata about a test; future events will refer to the test by its opaque ID.

### Class Definition
```dart
class TestStartEvent extends Event {
  String type = "testStart";

  // Metadata about the test that started.
  Test test;
}
```

### Notes
- If the test is skipped, its `TestDoneEvent` will have `skipped` set to `true`.
- The `test.metadata` field should not be used to determine if a test is skipped.
```

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

### Enable Verbose Stack Traces

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Control whether stack traces are trimmed to remove internal frames. Set to `true` to include all frames.

```yaml
verbose_trace: true
```

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

### Run Tests on Specific Platforms

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Execute tests on the browser (e.g., Chrome) or the Dart VM. You can specify multiple platforms to run tests on all of them.

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

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

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

### Checking Expectations with checks

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/README.md

Illustrates fundamental expectation checks using the `checks` library. Use these for direct comparisons and structural checks of values, lists, and strings.

```dart
check(someValue).equals(expectedValue);
check(someList).deepEquals(expectedList);
check(someString).contains('expected pattern');
```

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

### Shorthand for Cross-Platform Executable

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

A shorthand to define the same executable for all operating systems.

```yaml
define_platforms:
  chromium:
    name: Chromium
    extends: chrome

    settings:
      executable: chromium
```

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

### Provide Custom HTML Template

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Specifies the path to a custom HTML template file for tests run in an HTML environment. Local HTML files with the same name as the test take precedence.

```yaml
custom_html_template_path: path/to/custom_template.html
```

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

### Compile host.dart to JavaScript

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/tool/README.md

Use the Dart compiler to transform the host.dart file into a JavaScript file. This is necessary to update the browser-side runner.

```console
dart compile js tool/host.dart -o lib/src/runner/browser/static/host.dart.js
```

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

### Select Test Reporter

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Control the output format of test results using the `--reporter` flag. Options include 'compact', 'expanded', 'github', and 'json'. The 'github' reporter is the default when running in a GitHub Actions environment.

```bash
dart test --reporter=compact
```

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

### Basic String Matching with expect()

Source: https://github.com/dart-lang/test/blob/master/pkgs/matcher/README.md

Use `expect()` with matchers like `allOf`, `contains`, `isNot`, `startsWith`, and `endsWith` for complex string validations. Ensure all conditions within `allOf` are met.

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

void main() {
  test('.split() splits the string on the delimiter', () {
    expect('foo,bar,baz', allOf([
      contains('foo'),
      isNot(startsWith('bar')),
      endsWith('baz')
    ]));
  });
}
```

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

### Define Browser Test Preset

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

A preset that acts as a shortcut for running only browser tests by specifying a path.

```yaml
presets:
  # Shortcut for running only browser tests.
  browser:
    paths:
    - test/runner/browser
```

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

### Configure Platform-Specific Test Behavior

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Use `@OnPlatform` annotation or `onPlatform` parameter to apply configurations like `Timeout` or `Skip` to specific platforms. The last matching configuration wins if multiple platforms match.

```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)')
  });
}
```

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

### Define Suite Class

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Represents a test suite, including its ID, platform, and file path.

```dart
class Suite {
  // An opaque ID for the suite.
  int id;

  // The platform on which the suite is running.
  String platform;

  // The path to the suite's file, or `null` if that path is unknown.
  String? path;
}
```

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

### Define Browser Tests Preset

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/package_config.md

A preset configuration to run only browser tests by specifying a path. This serves as a shortcut for common testing scenarios.

```yaml
presets:
  browser:
    paths:
    - test/runner/browser
```

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

### Checking List Elements with `any`

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/README.md

Illustrates how to apply an expectation to any element within a list using the `any` expectation. This is useful for verifying that at least one element meets a certain condition.

```dart
check(someList).any((e) => e.isGreaterThan(0));
```

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

### Importing expectAsync and expectAsyncUntil in Dart Test

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/doc/migrating_from_matcher.md

Continue to import 'package:test/expect.dart' for the 'expectAsync' and 'expectAsyncUntil' APIs.

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

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

### Define and Validate Directory Structure in Dart Tests

Source: https://github.com/dart-lang/test/blob/master/pkgs/test_descriptor/README.md

Use `d.dir()` and `d.file()` to define a directory structure. This structure can be created using `Descriptor.create()` and verified using `Descriptor.validate()`. The descriptor operates within a temporary sandbox directory (`d.sandbox`) that is managed automatically.

```dart
import 'dart:io';

import 'package:test/test.dart';
import 'package:test_descriptor/test_descriptor.dart' as d;

void main() {
  test('Directory.rename', () async {
    await d.dir('parent', [
      d.file('sibling', 'sibling-contents'),
      d.dir('old-name', [d.file('child', 'child-contents')])
    ]).create();

    await Directory('${d.sandbox}/parent/old-name')
        .rename('${d.sandbox}/parent/new-name');

    await d.dir('parent', [
      d.file('sibling', 'sibling-contents'),
      d.dir('new-name', [d.file('child', 'child-contents')])
    ]).validate();
  });
}
```

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

### IDE Autocomplete Suggestions in Dart

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/doc/migrating_from_matcher.md

Illustrates the difference in IDE autocomplete suggestions between `matcher` and `checks`. `checks` provides more relevant suggestions based on the value type.

```dart
expect(actual, _ // many unrelated suggestions
```

```dart
check(actual)._ // specific suggestions
```

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

### Browser Test Connecting to Hybrid WebSocket Server

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Tests a WebSocket connection from a browser to a hybrid isolate. It uses spawnHybridUri to launch the server isolate and then connects to the WebSocket using the port provided by the isolate.

```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!'));
  });
}
```

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

### Include Tests by Tags

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `include_tags` with a boolean selector to run tests matching specific tags. Exclusions take precedence.

```yaml
presets:
  # Pass "-P windowless" to run tests that don't open browser windows.
  windowless:
    include_tags: !browser || content-shell
```

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

### AllSuitesEvent Definition

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Indicates the total number of suites that will be loaded. This event's position relative to others (except StartEvent) is not guaranteed due to asynchronous determination.

```dart
class AllSuitesEvent extends Event {
  String type = "allSuites";

  /// The total number of suites that will be loaded.
  int count;
}
```

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

### Dart File Header

Source: https://github.com/dart-lang/test/blob/master/CONTRIBUTING.md

All files in the Dart project must begin with this specific header, which includes copyright and licensing information.

```dart
// Copyright (c) 2023, 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.
```

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

### Specify Default Compilers

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use `compilers` to set the default compilers for tests. If a platform has no configured compiler, its default is used.

```yaml
compilers: [source]

compilers:
- source
```

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

### Custom HTML Template Configuration

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Configure a shared HTML template for all tests using `custom_html_template_path`. This template uses `{{testScript}}` and optionally `{{testName}}` placeholders.

```yaml
custom_html_template_path: html_template.html.tpl
```

```html
<!doctype html>
<!-- html_template.html.tpl -->
<html>
  <head>
    <title>{{testName}} Test</title>
    {{testScript}}
    <script src="packages/test/dart.js"></script>
  </head>
  <body>
    // ...
  </body>
</html>
```

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

### Run Tests in a Directory

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Execute all test files within a specified directory. The runner recursively searches for files matching the `*_test.dart` pattern.

```bash
dart test path/to/dir
```

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

### Configure Package-Wide Test Defaults

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Define global test configurations like default timeouts or platforms in the `dart_test.yaml` file. 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]
```

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

### Suite Model

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

Represents a test suite, which corresponds to a loaded test file. It includes a unique ID, the platform it's running on, and its file path.

```APIDOC
## Suite

### Description
A test suite corresponding to a loaded test file. The suite's ID is unique in the context of this test run. It's used elsewhere in the protocol to refer to this suite without including its full representation.

### Class Definition
```dart
class Suite {
  int id;
  String platform;
  String? path;
}
```

### Fields
- **id** (int) - An opaque ID for the suite.
- **platform** (String) - The platform on which the suite is running.
- **path** (String?) - The path to the suite's file, or `null` if that path is unknown.
```

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

### Configure File Reporters

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Specifies additional reporters to write output to files. Maps reporter names to file paths.

```yaml
file_reporters:
  json: reports/tests.json
```

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

### Filter Tests with Path Queries

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/README.md

Apply filters directly to test paths to narrow down which tests run. Supported filters include `name`, `full-name`, `line`, and `col`.

```bash
dart test "path/to/test.dart?line=10&col=2"
```

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

### Composing Multiple Expectations with Cascade Syntax

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/README.md

Demonstrates chaining multiple expectations on the same value using Dart's cascade syntax (`..`). This is suitable for sequential checks on a single subject.

```dart
check(someString)
  ..startsWith('a')
  ..endsWith('z')
  ..contains('lmno');
```

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

### Preset for Browser Tests with Filename

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Defines a preset for Chrome tests using a specific filename pattern and inherits browser test configurations.

```yaml
presets:
  # Shortcut for running only browser tests.
  browser:
    paths: [test/runner/browser]

  # Shortcut for running only Chrome tests.
  chrome:
    filename: "chrome_*_test.dart"
    add_presets: [browser]
```

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

### Enable JS Stack Trace Conversion

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Set `js_trace` to `true` to convert stack traces from Dart compiled to JS back to Dart style using source maps. Defaults to `false`.

```yaml
js_trace: true
```

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

### Enable Debugging Pause After Load

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Set `pause_after_load` to `true` to pause the test runner after each suite loads, before tests execute. This also sets `concurrency` to 1 and `timeout` to `none`.

```yaml
presets:
  # Pass "-P debug" to enable debugging configuration
  debug:
    pause_after_load: true
    exclude_tags: undebuggable
    reporter: expanded
```

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

### Check Stream Order and Completion

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/README.md

Use `check(someStream).withQueue.inOrder` to assert the sequence of emitted values from a stream and its eventual completion. This requires wrapping the stream in a `StreamQueue` if multiple expectations are needed on a single-subscription stream.

```dart
await check(someStream).withQueue.inOrder([
  (s) => s.emits((e) => e.equals(1)),
  (s) => s.emits((e) => e.equals(2)),
  (s) => s.emits((e) => e.equals(3)),
  (s) => s.isDone(),
]);
```

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

### Skip Tests with a Reason

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

Use the `skip` field within tags to skip tests and provide a reason. This is similar to the `skip` parameter for `test()`.

```yaml
tags:
  chrome:
    skip: "Our Chrome launcher is busted. See issue 1234."
```

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

### Define Debug Preset

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/configuration.md

A preset for ensuring completely un-munged stack traces by disabling verbose trace options.

```yaml
presets:
  # Use this when you need completely un-munged stack traces.
  debug:
    verbose_trace: false
    js_trace: true
```

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

### Testing Futures with completion() Matcher

Source: https://github.com/dart-lang/test/blob/master/pkgs/matcher/README.md

The `completion()` matcher is used with `expect()` to test `Futures`. It ensures the test waits for the `Future` to complete and then applies a matcher to its value. Requires `dart:async`.

```dart
import 'dart:async';

import 'package:test/test.dart';

void main() {
  test('Future.value() returns the value', () {
    expect(Future.value(10), completion(equals(10)));
  });
}
```

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

### Event - Root Class

Source: https://github.com/dart-lang/test/blob/master/pkgs/test/doc/json_reporter.md

The base class for all events emitted by the JSON reporter.

```APIDOC
## Event

### Description
This is the root class of the protocol. All root-level objects emitted by the JSON reporter will be subclasses of `Event`.

### Attributes
- **type** (String) - The type of the event. This is always one of the subclass types listed below.
- **time** (int) - The time (in milliseconds) that has elapsed since the test runner started.
```

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

### Adding Reason to Expectations

Source: https://github.com/dart-lang/test/blob/master/pkgs/checks/README.md

Shows how to provide additional context to an expectation failure by using the `because:` argument in `check()`. This is useful when the default failure message might lack clarity.

```dart
check(
  because: 'log lines must start with the severity',
  logLines,
).every((l) => l
  ..anyOf([
    (l) => l.startsWith('ERROR'),
    (l) => l.startsWith('WARNING'),
    (l) => l.startsWith('INFO'),
  ]));
```