test function

@isTest void test(Object? description, dynamic body(), { String? testOn, Timeout? timeout, Object? skip, Object? tags, Map<String, dynamic>? onPlatform, int? retry, @Deprecated('Debug only') @doNotSubmit bool solo = false, })

Creates a new test case with the given description (converted to a string) and body.

The description will be added to the descriptions of any surrounding groups. If testOn is passed, it's parsed as a platform selector; the test will only be run on matching platforms.

If timeout is passed, it's used to modify or replace the default timeout of 30 seconds. Timeout modifications take precedence in suite-group-test order, so timeout will also modify any timeouts set on the group or suite.

If skip is a String or true, the test is skipped. If it's a String, it should explain why the test is skipped; this reason will be printed instead of running the test. If a call to test is nested within a group, a non-null skip parameter for the test will take precedence over the skip parameter in the group. For instance, if a group is set to skip: true, but a test within it is configured as skip: false, the test will not be skipped. A suite level @Skip() annotation cannot be overridden with skip arguments to test or group.

If tags is passed, it declares user-defined tags that are applied to the test. These tags can be used to select or skip the test on the command line, or to do bulk test configuration. All tags should be declared in the package configuration file. The parameter can be an Iterable of tag names, or a String representing a single tag.

If retry is passed, the test will be retried the provided number of times before being marked as a failure.

onPlatform allows tests to be configured on a platform-by-platform basis. It's a map from strings that are parsed as PlatformSelectors to annotation classes: Timeout, Skip, or lists of those. These annotations apply only on the given platforms. For example:

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

If multiple platforms match, the annotations apply in order as through they were in nested groups.

If the solo flag is true, only tests and groups marked as "solo" will be be run. This only restricts tests within this test suite—tests in other suites will run as normal. We recommend that users avoid this flag if possible and instead use the test runner flag -n to filter tests by name.

Implementation

@isTest
void test(Object? description, dynamic Function() body,
    {String? testOn,
    Timeout? timeout,
    Object? skip,
    Object? tags,
    Map<String, dynamic>? onPlatform,
    int? retry,
    // TODO(https://github.com/dart-lang/test/issues/2205): Remove deprecated.
    @Deprecated('Debug only') @doNotSubmit bool solo = false}) {
  _declarer.test(description.toString(), body,
      testOn: testOn,
      timeout: timeout,
      skip: skip,
      onPlatform: onPlatform,
      tags: tags,
      retry: retry,
      solo: solo);

  // Force dart2js not to inline this function. We need it to be separate from
  // `main()` in JS stack traces in order to properly determine the line and
  // column where the test was defined. See sdk#26705.
  return;
  return; // ignore: dead_code
}