dart_dev 3.0.0-alpha.0

  • Readme
  • Changelog
  • Installing
  • 82

Dart Dev Tools #

Pub Build Status

Centralized tooling for Dart projects. Consistent interface across projects. Easily configurable.

Quick Start #

Upgrading from v2? Check out the upgrade guide.

Add dart_dev as a dev dependency in your project:

# pubspec.yaml
dev_dependencies:
  dart_dev: ^3.0.0

Create a tool/dev.dart file. This is where you will configure which dart developer tools are available for your project and how they should behave.

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

final config = {
  'analyze': AnalyzeTool(),
  'format': FormatTool(),
  'test': TestTool(),
  'serve': WebdevServeTool(),
};

Run any of these tools via the dart_dev command-line app:

$ pub run dart_dev analyze
[INFO] Running subprocess:
dartanalyzer .
--------------------------
Analyzing dart_dev...
No issues found!

We recommend adding a ddev alias:

alias ddev='pub run dart_dev'

Configure your project's tools as necessary:

// tool/dev.dart
import 'package:dart_dev/dart_dev.dart';
import 'package:glob/glob.dart';

final config = {
  'analyze': AnalyzeTool()
    ..dartanalyzerArgs = ['--fatal-infos'],
  'format': FormatTool()
    ..exclude = [Glob('lib/src/generated/**.dart')],
  'test': TestTool()
    ..testArgs = ['-P', 'unit'],
  'serve': WebdevServeTool()
    ..webdevArgs = ['--debug', 'example:8080', 'web:8081'],
};

Motivation & Goal

Most Dart projects eventually share a common set of development requirements (e.g. static analysis, formatting, test running, serving, etc.). The Dart SDK along with some core packages supply the necessary tooling for these developer tasks (e.g. dartanalyzer, dartfmt, or pub run test).

While the core tooling gets us far, there are two areas in which we feel it falls short:

  1. Inconsistencies across projects in how these tools must be used in order to to accomplish common developer tasks.

  2. Functionality gaps for more complex use cases.

With dart_dev, we attempt to address #1 by providing a way to configure all of these common developer tasks at the project level, and #2 by composing additional functionality around existing tools.

This package is built with configurability and extensiblity in mind, with the hope that you and your teams will find value in creating your own tools and shared configurations. Ideally, you or your team can settle on a shared configuration that individual projects can consume; projects with unique requirements can tweak the configuration as necessary; and developers can rely on the convention of a simple, consistent command-line interface regardless of the project they are in.

Project-Level Configuration #

Every task should be able to be configured at the project-level so that any variance across projects becomes a configuration detail that need not be memorized or referenced in order to run said task.

Consider formatting as an example. The default approach to formatting files is to run dartfmt -w .. But, some projects may want to exclude certain files that would otherwise be formatted by this command. Or, some projects may want to use pub run dart_style:format instead of dartfmt. Currently, there is no project-level configuration supported by the formatter, so these sorts of things just have to be documented in a README.md or CONTRIBUTING.md.

With dart_dev, this can be accomplished like so:

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

final config = {
  'format': FormatTool()
    ..exclude = [Glob('lib/src/**.g.dart')]
    ..formatter = Formatter.dartStyle,
};
$ ddev format
[INFO] Running subprocess:
pub run dart_style:format -w <3 paths>
--------------------------------------
Unchanged ./lib/foo.dart
Unchanged ./lib/src/bar.dart
Formatted ./lib/src/baz.dart

Extending/Composing Functionality #

Using existing tooling provided by (or conventionalized by) the Dart community should always be the goal, but the reality is that there are gaps. Certain use cases can be made more convenient and new use cases may arise.

Consider test running as an example. For simple projects, pub run test is sufficient. In fact, the test package supports a huge amount of project-level configuration via dart_test.yaml, which means that for projects that are properly configured, pub run test just works.

Unfortunately, at this time, projects that rely on builders must run tests via pub run build_runner test. Based on the project, you would need to know which test command should be run.

With dart_dev, the TestTool handles this automatically by checking the project's pubspec.yaml for a dependency on build_test. If present, tests will be run via pub run build_runner test, otherwise it falls back to the default of pub run test.

# In a project without a `build_test` dependency:
$ ddev test
[INFO] Running subprocess:
pub run test
----------------------------
00:01 +75: All tests passed!


# In a project with a `build_test` dependency:
$ ddev test
[INFO] Running subprocess:
pub run build_runner test
----------------------------
[INFO] Generating build script completed, took 425ms
[INFO] Creating build script snapshot... completed, took 13.6s
[INFO] Building new asset graph completed, took 960ms
[INFO] Checking for unexpected pre-existing outputs. completed, took 1ms
[INFO] Running build completed, took 12.4s
[INFO] Caching finalized dependency graph completed, took 71ms
[INFO] Creating merged output dir `/var/folders/vb/k8ccjw095q16jrwktw31ctmm0000gn/T/build_runner_testBkm6gS/` completed, took 260ms
[INFO] Writing asset manifest completed, took 3ms
[INFO] Succeeded after 12.8s with 1276 outputs (2525 actions)
Running tests...

00:00 +75: All tests passed!

Additionally, TestTool automatically applies --build-filter options to the pub run build_runner test command to help reduce build time and speed up dev iteration when running a subset of the available tests.

Generally speaking, these dart tool abstractions provide a place to address functionality gaps in the underlying tools or make certain use cases more convenient or efficient.

Check out the API documentation to see all of the available tools, their configuration options, and details on how they work.

Shared Configuration #

This package provides coreConfig as a minimal base configuration of dart_dev tools.

To use this shared config in your project:

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

final config = coreConfig;

This shared config contains the following targets:

  • ddev analyze
  • ddev format
  • ddev serve
  • ddev test

The actual configuration of each of these targets can be found here: lib/src/core_config.dart

coreConfig is just a getter that returns a Map<String, DevTool> object, so extending it or customizing it is as easy as creating your own Map, spreading the shared config, and then adding your own entries:

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

final config = {
  ...coreConfig,

  // Override a target by including it after `...coreConfig`:
  'format': FormatTool()
    ..formatter = Formatter.dartStyle,

  // Add a custom target:
  'github': ProcessTool(
      'open', ['https://github.com/Workiva/dart_dev']),

  // etc.
};

Changelog #

3.0.0-alpha #

TODO

2.0.6 #

  • Improvement: On dart 2, the test task now properly sets a non-zero exit code if the build fails. As a result, it also no longer runs a separate pub run build_runner build prior to running tests.

2.0.5 #

  • Improvement: Added config.test.deleteConflictingOutputs that when enabled will include the --delete-conflicting-outputs flag when running tests via build_runner.

  • Bug Fix: Fix a type-related RTE in the TaskProcess class.

2.0.4 #

  • Bug Fix: When on Dart 2 and the package has a dependency on build_test, the test task will now properly exit with a non-zero exit code if the build fails.

2.0.3 #

  • Feature: Use --disable-serve-std-out or set config.test.disableServeStdOut = true with the test task to silence the pub serve output.

2.0.2 #

  • Improvement: The test task now fails early if running on Dart 2 with either the dartium or content-shell platforms are selected.

  • Bug Fix: Prevent a null exception in the reporter when running on Dart

    =2.1.0.

2.0.1 #

December 11, 2018

  • Bug Fix: The format task now ignores the .dart_tool/ directory. Prior to this, it would try to format .dart files in .dart_tool/, often resulting in ProcessException: Argument list too long errors.

2.0.0 #

October 11, 2018

  • BREAKING CHANGE: docs, examples, and saucelabs tasks have been removed.

  • BREAKING CHANGE: ExamplesTask and serveExamples have been removed from the package:dart_dev/api.dart entry point.

  • BREAKING CHANGE: SaucePlatform and the constant platform instances have been removed from the package:dart_dev/dart_dev.dart entry point.

  • Improvement: Dart 2 compatible!

    Notable change to the test task: Pub serve functionality is now ignored when running the test task on Dart 2, as that functionality was removed from the pub executable as a part of the Dart 2.0.0 SDK release. To accommodate this change, the test task will now run tests via build_runner test when on Dart 2 and when build_test is found in your package's pubspec.yaml.

    Caveat: The coverage task exits with a non-zero exit code immediately when run on Dart2, as there is not yet any support for collecting coverage from browser tests.

1.10.1 #

October 9, 2018

  • Deprecations: The following members of the package:dart_dev/dart_dev.dart entry point have been deprecated and will be removed in 2.0.0:

    • SaucePlatform
    • const SaucePlatform chrome
    • const SaucePlatform chromeWindows
    • const SaucePlatform chromeOsx
    • const SaucePlatform firefoxWindows
    • const SaucePlatform firefoxOsx
    • const SaucePlatform safari
    • const SaucePlatform ie10
    • const SaucePlatform ie11

1.10.0 #

October 8, 2018

  • New Tasks: dart1-only and dart2-only

    Use these tasks to conditionally run another dart_dev task or an arbitrary shell command only when running on Dart1 or Dart2.

      # Run a dart_dev task only on Dart1:
      $ ddev dart1-only test
    
      # Run a dart_dev task with additional args only on Dart1:
      $ ddev dart1-only -- format --check
    
      # Run an shell script only on Dart1:
      $ ddev dart1-only ./example.sh
    
      # Run an executable with additional args only on Dart1:
      $ ddev dart1-only -- pub serve web --port 8080
    
      # The `dart2-only` task works exactly the same, but only runs on Dart2:
      $ ddev dart2-only test
      $ ddev dart2-only -- format --check
      $ ddev dart2-only ./example.sh
      $ ddev dart2-only -- pub run build_runner serve web:8080
    
  • Deprecated Tasks: docs, examples, and saucelabs.

    These three tasks have been deprecated and will be removed in 2.0.0.

1.1.2 #

March 22, 2016

  • Bug fix: The test reporter output now respects the --no-color flag.

  • Bug fix: The test task was previously running the unit test suite even when it was disabled. This has been fixed. Additionally, passing in individual test files/directories overrides the unit and integration suites.

1.1.1 #

February 24, 2016

  • Bug fix: 1.1.0 introduced a regression that caused the test task to no longer default to running the unit test suite and instead run all tests in the test/ directory when the --unit flag was not explicitly set. This has been fixed and should match the behavior from before 1.1.0.

1.1.0 #

February 23, 2016

  • Improvement: Set the coverage task's exit code to non-zero when a test fails.

  • Improvement: Add support for the -n, --name arg for the test task.

  • Bug fix: Catch and silence exception when reading a non-utf8 file during the copy-license task.

  • Bug fix: Make sure the test task observes the --no-unit flag.

1.0.6 #

December 16, 2015

  • Improvement: --strong flag added to the Analyze task.

  • Improvement: The Analyze task's --fatal-hints flag is now implemented by utilizing the --fatal-hints flag on dartanalyzer instead of parsing the output.

  • Documentation: Add zsh completion instructions to the README.

1.0.5 #

November 25, 2015

New Feature: pub server support for tests and coverage #

  • The Test and Coverage tasks now take a --pub-serve flag that will automatically spin up a pub server that is used to run the tests.

  • Tests that require a pub transformer can now be run by passing in this flag!

Changes #

  • Improvement: --fatal-hints flag added to the Analyze task.

1.0.4 #

November 20, 2015

  • Tooling: Bash completions are available in the tool/ directory! See the README for installation instructions.

  • Bug Fix: Dart 1.13 introduced a change to the dart2js output on which the coverage task relied for dart:html detection. This has been fixed.

1.0.3 #

November 12, 2015

  • Improvement: The test task can now run individual test files:

      ddev test test/path/to/test.dart
    
  • Improvement: Widen the dartdoc dependency range.

1.0.2 #

October 15, 2015

  • Improvement: The copy-license task now trims empty leading and trailing lines.

  • Bug Fix: Coverage task no longer incorrectly ignores test files that don't end in _test.dart.

1.0.1 #

September 8, 2015

New Task: docs

  • ddev docs or pub run dart_dev docs

  • Documentation generation via the dartdoc package.

Changes #

  • Improvement: The coverage task now checks for the lcov dependency before trying to generate the HTML report. If missing, installation instructions are given.

  • Improvement: The dependency range for the dart_style package has been widened to >=0.1.8 <0.3.0 to avoid dependency version conflicts.

  • Bug Fix: Fixed a bug that could prevent the HTML coverage report from being opened automatically.

  • Bug Fix: When running the examples task, pub serve errors no longer cause the process to exit prematurely.

1.0.0 #

August 20, 2015

  • Initial version of dart_dev

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dart_dev: ^3.0.0-alpha.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:dart_dev/dart_dev.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
70
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
85
Overall:
Weighted score of the above. [more]
82
Learn more about scoring.

We analyzed this package on Nov 4, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.6.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, other

Primary library: package:dart_dev/dart_dev.dart with components: io.

Health suggestions

Fix lib/src/tools/test_tool.dart. (-0.50 points)

Analysis of lib/src/tools/test_tool.dart reported 1 hint:

line 9 col 8: Unused import: 'package:path/path.dart'.

Maintenance suggestions

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and dart_dev.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.3.0 <3.0.0
args ^1.5.2 1.5.2
async ^2.3.0 2.4.0
build_runner ^1.7.0 1.7.2
completion ^0.2.1+1 0.2.1+1
glob ^1.1.7 1.2.0
io ^0.3.3 0.3.3
logging ^0.11.3+2 0.11.3+2
path ^1.6.2 1.6.4
pedantic ^1.7.0 1.8.0+1
pub_semver ^1.4.2 1.4.2
pubspec_parse ^0.1.4 0.1.5
stack_trace ^1.9.3 1.9.3
yaml ^2.1.16 2.2.0
Transitive dependencies
analyzer 0.38.5 0.39.1
analyzer_plugin 0.2.1
build 1.2.1
build_config 0.4.1+1
build_daemon 2.1.0
build_resolvers 1.2.1 1.2.2
build_runner_core 4.1.0
built_collection 4.2.2
built_value 6.8.2 7.0.0
built_value_generator 6.8.2 7.0.0
charcode 1.1.2
checked_yaml 1.0.2
code_builder 3.2.0
collection 1.14.12
convert 2.1.1
crypto 2.1.3
csslib 0.16.1
dart_style 1.3.3
fixnum 0.10.11
front_end 0.1.27 0.1.29
graphs 0.2.0
html 0.14.0+3
http 0.12.0+2
http_multi_server 2.1.0
http_parser 3.1.3
js 0.6.1+1
json_annotation 3.0.0
kernel 0.3.27 0.3.29
meta 1.1.8
mime 0.9.6+3
node_interop 1.0.3
node_io 1.0.1+2
package_config 1.1.0
package_resolver 1.0.10
pool 1.4.0
quiver 2.1.1
shelf 0.7.5
shelf_web_socket 0.2.3
source_gen 0.9.4+6
source_span 1.5.5
stream_channel 2.0.0
stream_transform 0.0.19
string_scanner 1.0.5
term_glyph 1.1.0
timing 0.1.1+2
typed_data 1.1.6
watcher 0.9.7+12
web_socket_channel 1.1.0
Dev dependencies
dependency_validator ^1.3.0
matcher ^0.12.5 0.12.6
test ^1.6.4