Skip to content

test-tool.md

Latest commit

 

History

History
179 lines (136 loc) · 6.35 KB

test-tool.md

File metadata and controls

179 lines (136 loc) · 6.35 KB

TestTool

Runs dart tests for the current project.

Usage

This tool is included in the coreConfig and is runnable by default via ddev test.

// tool/dart_dev/config.dart
import 'package:dart_dev/dart_dev.dart';

final config = {
  'test': TestTool() // configure as necessary
};

test vs build_runner test

Historically, dart test has been the canonical way to run Dart tests. With the introduction of the build system, there is now a second way to run tests. Projects that rely on builder outputs must run tests via dart run build_runner test.

The TestTool will make this choice for you. If the current project has a dependency on build_test, it will run dart run build_runner test. Otherwise it will default to running dart test.

It appears as though the long term goal is to integrate the build system into the test runner so that dart test is once again the canonical way to run tests.

Default behavior

By default this tool will run dart test, unless there is a dependency on build_test, in which case it will run dart run build_runner test.

Running a subset of tests

When developing it is common to want to run a targeted subset of tests. The test runner supports targeting tests by path(s), preset(s), or by matching against the test descriptions. These common command-line options are available when running the TestTool via ddev test, as well.

$ ddev help test
Run dart tests in this package.

Usage: dart_dev test [files or directories...]
======== Selecting Tests
-n, --name              A substring of the name of the test to run.
                        Regular expression syntax is supported.
                        If passed multiple times, tests must match all substrings.

-N, --plain-name        A plain-text substring of the name of the test to run.
                        If passed multiple times, tests must match all substrings.

======== Running Tests
-P, --preset            The configuration preset(s) to use.
    --[no-]release      Build with release mode defaults for builders.
                        This only applies in projects that run tests with build_runner.

======== Output
    --reporter          The runner used to print test results.

          [compact]     A single line, updated continuously.
          [expanded]    A separate line for each update.
          [json]        A machine-readable format (see https://goo.gl/gBsV1a).

======== Other Options
    --test-stdout       Write the test process stdout to this file path.
    --test-args         Args to pass to the test runner process.
                        Run "dart test -h -v" to see all available options.

    --build-args        Args to pass to the build runner process.
                        Run "dart run build_runner test -h -v" to see all available options.
                        Note: these args are only applicable if the current project depends on "build_test".

-h, --help              Print this usage information.

Additionally, in projects that use build_runner to run tests, the TestTool will automatically apply build filters so that the build system only builds the set of outputs necessary for running the targeted test paths. In large projects, this can significantly reduce the build time which makes iterating on tests much more efficient.

$ ddev test test/foo/bar/ test/baz_test.dart
[INFO] Running subprocess:
dart run build_runner test --build-filter=test/foo/bar/** --build-filter=test/baz_test.dart.*_test.dart.js --build-filter=test/baz_test.html -- test/foo/bar/ test/baz_test.dart
----------------------------------------------------------------------------

Collecting coverage

The test package now has partial support for coverage collection built-in. As of now, it is only supported for tests run on the Dart VM. Follow this issue for updates on implementing coverage collection for tests run in Chrome.

There are plans to add a "coverage" mode to the TestTool that will pass the coverage directory to the test command and handle formatting the coverage output to a more consumable format like lcov. It will optionally generate and open an HTML report using the genhtml tool.

Configuration

Always prefer configuring the test runner via dart_test.yaml when possible. This ensures that other tools that leverage the test runner benefit from the configuration, as well.

Passing args to the test process

// tool/dart_dev/config.dart
import 'package:dart_dev/dart_dev.dart';

final config = {
  'test': TestTool()
    ..testArgs = ['--no-chain-stack-traces']
};

Passing args to the build_runner process

Note that this is only applicable in projects that run tests via build_runner.

// tool/dart_dev/config.dart
import 'package:dart_dev/dart_dev.dart';

final config = {
  'test': TestTool()
    ..buildArgs = ['--delete-conflicting-outputs']
};

Command-line options

$ ddev help test