Add support for sharding test runs.

lib/src/runner/configuration.dart

 // Copyright (c) 2015, 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.
 
 import 'dart:io';
 
 import 'package:boolean_selector/boolean_selector.dart';
 import 'package:collection/collection.dart';
 import 'package:glob/glob.dart';
 import 'package:path/path.dart' as p;
@@ skipping 74 matching lines @@
 
   /// Whether to use command-line color escapes.
   bool get color => _color ?? canUseSpecialChars;
   final bool _color;
 
   /// How many tests to run concurrently.
   int get concurrency =>
       pauseAfterLoad ? 1 : (_concurrency ?? defaultConcurrency);
   final int _concurrency;
 
+  /// The index of the current shard, if sharding is in use, or `null` if it's
+  /// not.
+  ///
+  /// Sharding is a technique that allows the Google internal test framework to
+  /// easily split a test run across multiple workers without requiring the
+  /// tests to be modified by the user. When sharding is in use, the runner gets
+  /// a shard index (this field) and a total number of shards, and is expected
+  /// to provide the following guarantees:
+  ///
+  /// * Running the same invocation of the runner, with the same shard index and
+  ///   total shards, will run the same set of tests.
+  /// * Across all shards, each test must be run exactly once.
+  ///
+  /// In addition, tests should be balanced across shards as much as possible.
+  final int shardIndex;
+
+  /// The total number of shards, if sharding is in use, or `null` if it's not.
+  ///
+  /// See [shardIndex] for details.
+  final int totalShards;
+
   /// The paths from which to load tests.
   List<String> get paths => _paths ?? ["test"];
   final List<String> _paths;
 
   /// Whether the load paths were passed explicitly or the default was used.
   bool get explicitPaths => _paths != null;
 
   /// The glob matching the basename of tests to run.
   ///
   /// This is used to find tests within a directory.
@@ skipping 137 matching lines @@
       bool jsTrace,
       bool skip,
       String skipReason,
       PlatformSelector testOn,
       bool pauseAfterLoad,
       bool color,
       String packageRoot,
       String reporter,
       int pubServePort,
       int concurrency,
+      int shardIndex,
+      int totalShards,
       Timeout timeout,
       Iterable<Pattern> patterns,
       Iterable<TestPlatform> platforms,
       Iterable<String> paths,
       Glob filename,
       Iterable<String> chosenPresets,
       BooleanSelector includeTags,
       BooleanSelector excludeTags,
       Iterable addTags,
       Map<BooleanSelector, Configuration> tags,
       Map<PlatformSelector, Configuration> onPlatform,
       Map<String, Configuration> presets}) {
     _unresolved() => new Configuration._(
         help: help,
         version: version,
         verboseTrace: verboseTrace,
         jsTrace: jsTrace,
         skip: skip,
         skipReason: skipReason,
         testOn: testOn,
         pauseAfterLoad: pauseAfterLoad,
         color: color,
         packageRoot: packageRoot,
         reporter: reporter,
         pubServePort: pubServePort,
         concurrency: concurrency,
+        shardIndex: shardIndex,
+        totalShards: totalShards,
         timeout: timeout,
         patterns: patterns,
         platforms: platforms,
         paths: paths,
         filename: filename,
         chosenPresets: chosenPresets,
         includeTags: includeTags,
         excludeTags: excludeTags,
         addTags: addTags,
 
@@ skipping 44 matching lines @@
           bool jsTrace,
           bool skip,
           this.skipReason,
           PlatformSelector testOn,
           bool pauseAfterLoad,
           bool color,
           String packageRoot,
           String reporter,
           int pubServePort,
           int concurrency,
+          this.shardIndex,
+          this.totalShards,
           Timeout timeout,
           Iterable<Pattern> patterns,
           Iterable<TestPlatform> platforms,
           Iterable<String> paths,
           Glob filename,
           Iterable<String> chosenPresets,
           BooleanSelector includeTags,
           BooleanSelector excludeTags,
           Iterable addTags,
           Map<BooleanSelector, Configuration> tags,
@@ skipping 26 matching lines @@
         excludeTags = excludeTags ?? BooleanSelector.none,
         addTags = new UnmodifiableSetView(addTags?.toSet() ?? new Set()),
         tags = _map(tags),
         onPlatform = _map(onPlatform),
         presets = _map(presets) {
     if (_filename != null && _filename.context.style != p.style) {
       throw new ArgumentError(
           "filename's context must match the current operating system, was "
               "${_filename.context.style}.");
     }
+
+    if ((shardIndex == null) != (totalShards == null)) {
+      throw new ArgumentError(
+          "shardIndex and totalShards may only be passed together.");
+    } else if (shardIndex != null) {
+      RangeError.checkValueInInterval(
+          shardIndex, 0, totalShards - 1, "shardIndex");
+    }
   }
 
   /// Returns a [input] as an unmodifiable list or `null`.
   ///
   /// If [input] is `null` or empty, this returns `null`. Otherwise, it returns
   /// `input.toList()`.
   static List _list(Iterable input) {
     if (input == null) return null;
     input = new List.unmodifiable(input);
     if (input.isEmpty) return null;
@@ skipping 22 matching lines @@
         jsTrace: other._jsTrace ?? _jsTrace,
         skip: other._skip ?? _skip,
         skipReason: other.skipReason ?? skipReason,
         testOn: testOn.intersection(other.testOn),
         pauseAfterLoad: other._pauseAfterLoad ?? _pauseAfterLoad,
         color: other._color ?? _color,
         packageRoot: other._packageRoot ?? _packageRoot,
         reporter: other._reporter ?? _reporter,
         pubServePort: (other.pubServeUrl ?? pubServeUrl)?.port,
         concurrency: other._concurrency ?? _concurrency,
+        shardIndex: other.shardIndex ?? shardIndex,
+        totalShards: other.totalShards ?? totalShards,
         timeout: timeout.merge(other.timeout),
         patterns: patterns.union(other.patterns),
         platforms: other._platforms ?? _platforms,
         paths: other._paths ?? _paths,
         filename: other._filename ?? _filename,
         chosenPresets: chosenPresets.union(other.chosenPresets),
         includeTags: includeTags.intersection(other.includeTags),
         excludeTags: excludeTags.union(other.excludeTags),
         addTags: other.addTags.union(addTags),
         tags: _mergeConfigMaps(tags, other.tags),
@@ skipping 17 matching lines @@
       bool jsTrace,
       bool skip,
       String skipReason,
       PlatformSelector testOn,
       bool pauseAfterLoad,
       bool color,
       String packageRoot,
       String reporter,
       int pubServePort,
       int concurrency,
+      int shardIndex,
+      int totalShards,
       Timeout timeout,
       Iterable<Pattern> patterns,
       Iterable<TestPlatform> platforms,
       Iterable<String> paths,
       Glob filename,
       Iterable<String> chosenPresets,
       BooleanSelector includeTags,
       BooleanSelector excludeTags,
       Iterable addTags,
       Map<BooleanSelector, Configuration> tags,
       Map<PlatformSelector, Configuration> onPlatform,
       Map<String, Configuration> presets}) {
     return new Configuration(
         help: help ?? _help,
         version: version ?? _version,
         verboseTrace: verboseTrace ?? _verboseTrace,
         jsTrace: jsTrace ?? _jsTrace,
         skip: skip ?? _skip,
         skipReason: skipReason ?? this.skipReason,
         testOn: testOn ?? this.testOn,
         pauseAfterLoad: pauseAfterLoad ?? _pauseAfterLoad,
         color: color ?? _color,
         packageRoot: packageRoot ?? _packageRoot,
         reporter: reporter ?? _reporter,
         pubServePort: pubServePort ?? pubServeUrl?.port,
         concurrency: concurrency ?? _concurrency,
+        shardIndex: shardIndex ?? this.shardIndex,
+        totalShards: totalShards ?? this.totalShards,
         timeout: timeout ?? this.timeout,
         patterns: patterns ?? this.patterns,
         platforms: platforms ?? _platforms,
         paths: paths ?? _paths,
         filename: filename ?? _filename,
         chosenPresets: chosenPresets ?? this.chosenPresets,
         includeTags: includeTags ?? this.includeTags,
         excludeTags: excludeTags ?? this.excludeTags,
         addTags: addTags ?? this.addTags,
         tags: tags ?? this.tags,
         onPlatform: onPlatform ?? this.onPlatform,
         presets: presets ?? this.presets);
   }
 
   /// Merges two maps whose values are [Configuration]s.
   ///
   /// Any overlapping keys in the maps have their configurations merged in the
   /// returned map.
   Map<Object, Configuration> _mergeConfigMaps(Map<Object, Configuration> map1,
           Map<Object, Configuration> map2) =>
       mergeMaps(map1, map2,
           value: (config1, config2) => config1.merge(config2));
 }