Add suite information to the JSON reporter.

json_reporter.md

 JSON Reporter Protocol
 ======================
 
 The test runner supports a JSON reporter which provides a machine-readable
 representation of the test runner's progress. This reporter is intended for use
 by IDEs and other tools to present a custom view of the test runner's operation
 without needing to parse output intended for humans.
 
 Note that the test runner is highly asynchronous, and users of this protocol
 shouldn't make assumptions about the ordering of events beyond what's explicitly
@@ skipping 83 matching lines @@
   String protocolVersion;
 
   // The version of the test runner being used.
   String runnerVersion;
 }
 ```
 
 A single start event is emitted before any other events. It indicates that the
 test runner has started running.
 
+### SuiteEvent
+
+```
+class SuiteEvent extends Event {
+  String type = "suite";
+
+  /// Metadata about the suite.
+  Suite suite;
+}
+```
+
+A suite event is emitted before any `GroupEvent`s for groups in a given test
+suite. This is the only event that contains the full metadata about a suite;
+future events will refer to the suite by its opaque ID.
+
 ### GroupEvent
 
 ```
 class GroupEvent extends Event {
   String type = "group";
 
   /// Metadata about the group.
   Group group;
 }
 ```
@@ skipping 129 matching lines @@
 ### Test
 
 ```
 class Test {
   // An opaque ID for the test.
   int id;
 
   // The name of the test, including prefixes from any containing groups.
   String name;
 
+  // The ID of the suite containing this test.
+  int suiteID;
+
   // The IDs of groups containing this test, in order from outermost to
   // innermost.
   List<int> groupIDs;
 
   // The test's metadata, including metadata from any containing groups.
   Metadata metadata;
 }
 ```
 
 A single test case. The test's ID is unique in the context of this test run.
 It's used elsewhere in the protocol to refer to this test without including its
 full representation.
 
 Most tests will have at least one group ID, representing the implicit root
 group. However, some may not; these should be treated as having no group
 metadata.
 
+### Suite
+
+```
+class Suite {
+  // An opaque ID for the group.
+  int id;
+
+  // The platform on which the suite is running.
+  String? platform;
+
+  // The path to the suite's file.
+  String path;
+}
+```
+
+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.
+
+A suite's platform is one of the platforms that can be passed to the
+`--platform` option, or `null` if there is no platform (for example if the file
+doesn't exist at all). Its path is relative to the root of the current package.

[alexander.doroshko, 2016/02/11 14:26:43]

Spec says that Suite.path is relative to the current package root, but in fact
we see that absolute paths are emitted. 
Current implementation in IntelliJ IDEA works fine with absolute paths, so we'd
be happy with just a spec update.
If you believe that JSON reporter should be changed to emit relative paths
please let us know asap as IntelliJ IDEA and WebStorm releases are very soon.

[nweiz, 2016/02/12 00:58:25]

Good to know. I put out https://codereview.chromium.org/1690053004 to update the
docs.

I suspect what happens here is that we emit absolute paths if we're passed
absolute paths and vice versa, but I don't want to guarantee that behavior.

+
+Suites don't include their own metadata. Instead, that metadata is present on
+the root-level group.
+
 ### Group
 
 ```
 class Group {
   // An opaque ID for the group.
   int id;
 
   // The name of the group, including prefixes from any containing groups.
   String? name;
 
+  // The ID of the suite containing this group.
+  int suiteID;
+
   // The ID of the group's parent group, unless it's the root group.
   int? parentID;
 
   // The group's metadata, including metadata from any containing groups.
   Metadata metadata;
 }
 ```
 
 A group containing test cases. The group's ID is unique in the context of this
-test run. It's used elsewhere in the protocol to refer to this test without
+test run. It's used elsewhere in the protocol to refer to this group without
 including its full representation.
 
 The implicit group at the root of each test suite has `null` `name` and
 `parentID` attributes.
 
 ### Metadata
 
 ```
 class Metadata {
   // Whether the test case will be skipped by the test runner.
   bool skip;
 
   // The reason the test case is skipped, if the user provided it.
   String? skipReason;
 }
 ```
 
 The metadata attached to a test by a user.