[inspector] extend protocol for code coverage.

src/inspector/js_protocol.json

 {
     "version": { "major": "1", "minor": "2" },
     "domains": [
     {
         "domain": "Schema",
         "description": "Provides information about the protocol schema.",
         "types": [
             {
                 "id": "Domain",
                 "type": "object",
@@ skipping 186 matching lines @@
             {
                 "id": "StackTrace",
                 "type": "object",
                 "description": "Call frames for assertions or error messages.",
                 "properties": [
                     { "name": "description", "type": "string", "optional": true, "description": "String label of this stack trace. For async traces this may be a name of the function that initiated the async call." },
                     { "name": "callFrames", "type": "array", "items": { "$ref": "CallFrame" }, "description": "JavaScript function name." },
                     { "name": "parent", "$ref": "StackTrace", "optional": true, "description": "Asynchronous JavaScript stack trace that preceded this stack, if available." },
                     { "name": "promiseCreationFrame", "$ref": "CallFrame", "optional": true, "experimental": true, "description": "Creation frame of the Promise which produced the next synchronous trace when resolved, if available." }
                 ]
+            },
+            {   "id": "CoverageRange",
+                "type": "object",
+                "description": "Coverage data for a source range.",
+                "properties": [

[pfeldman, 2017/02/16 21:23:09]

experimental: true

[Yang, 2017/02/20 11:24:42]

Done.

+                    { "name": "functionName", "type": "string", "description": "JavaScript function name." },

[pfeldman, 2017/02/16 21:23:09]

Make it optional: not all of the ranges will have associated function names in
the future.

[Yang, 2017/02/20 11:24:42]

I now changed the structure so that we have this hierarchy: ScriptCoverage ->
FunctionCoverage -> CoverageRange.

For now each function has only one CoverageRange object. But in the future this
will change.

+                    { "name": "startLineNumber", "type": "integer", "description": "JavaScript script line number (0-based) for the range start." },
+                    { "name": "startColumnNumber", "type": "integer", "description": "JavaScript script column number (0-based) for the range start." },
+                    { "name": "endLineNumber", "type": "integer", "description": "JavaScript script line number (0-based) for the range end." },
+                    { "name": "endColumnNumber", "type": "integer", "description": "JavaScript script column number (0-based) for the range end." },
+                    { "name": "nested", "type": "array", "items": { "$ref": "CoverageRange" }, "description": "Nested inner coverage ranges." },

[pfeldman, 2017/02/16 21:23:09]

I'd drop this.

[Yang, 2017/02/20 11:24:42]

Done.

+                    { "name": "count", "type": "integer", "description": "Collected execution count of the source range." }
+                ]
+            },
+            {
+                "id": "ScriptCoverage",
+                "type": "object",
+                "description": "Coverage data for a script.",
+                "properties": [
+                    { "name": "scriptId", "$ref": "ScriptId", "description": "JavaScript script id." },
+                    { "name": "url", "type": "string", "description": "JavaScript script name or url." },
+                    { "name": "toplevel", "$ref": "CoverageRange", "description": "Coverage ranges for the top-level function." }

[pfeldman, 2017/02/16 21:23:09]

I'd just flatten array of ranges.

[Yang, 2017/02/16 21:30:51]

Wouldn't you have to reconstruct the nesting on the frontend?

[pfeldman, 2017/02/16 23:04:51]

We might be implying different nesting. If we are talking nested functions, then
no, we don't need nesting in the front-end. But if we are talking about
statement-level ranges within the function, then yes, we need one level nesting.
In other words, we could have 

{ scriptId: id,
  functions: [
    { functionName, functionRange, ranges: [{from, to, count}] }
  ]
}

[Yang, 2017/02/17 05:35:54]

In that case I suggest introducing a new type for inner ranges inside the
function for future statement-level coverage, once we have that, since these
ranges do not have function name associated. The functionName field would also
become non-optional.

But how come you don't care about nesting? Inner functions split the range of
its outer function, so you would have different counts associated with the
source positions in a function depending on whether it overlaps with an inner
function or not. Is that not necessary for the UI?

[pfeldman, 2017/02/17 17:59:39]

function for future statement-level coverage.

Isn't it exactly what I suggest above in the schema? You have scripts with
functions, functions are identified by names and ranges. Each function has a
list of blocks with counters, these blocks ranges don't intersect. So we
wouldn't need to do anything with the nesting.

[Yang, 2017/02/20 11:24:42]

Done.

+                ]
             }
         ],
         "commands": [
             {
                 "name": "evaluate",
                 "parameters": [
                     { "name": "expression", "type": "string", "description": "Expression to evaluate." },
                     { "name": "objectGroup", "type": "string", "optional": true, "description": "Symbolic group name that can be used to release multiple objects." },
                     { "name": "includeCommandLineAPI", "type": "boolean", "optional": true, "description": "Determines whether Command Line API should be available during the evaluation." },
                     { "name": "silent", "type": "boolean", "optional": true, "description": "In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides <code>setPauseOnException</code> state." },
@@ skipping 119 matching lines @@
                     { "name": "includeCommandLineAPI", "type": "boolean", "optional": true, "description": "Determines whether Command Line API should be available during the evaluation." },
                     { "name": "returnByValue", "type": "boolean", "optional": true, "description": "Whether the result is expected to be a JSON object which should be sent by value." },
                     { "name": "generatePreview", "type": "boolean", "optional": true, "description": "Whether preview should be generated for the result." },
                     { "name": "awaitPromise", "type": "boolean", "optional": true, "description": "Whether execution should wait for promise to be resolved. If the result of evaluation is not a Promise, it's considered to be an error." }
                 ],
                 "returns": [
                     { "name": "result", "$ref": "RemoteObject", "description": "Run result." },
                     { "name": "exceptionDetails", "$ref": "ExceptionDetails", "optional": true, "description": "Exception details."}
                 ],
                 "description": "Runs script with given id in a given context."
+            },
+            {
+                "name": "startPreciseCoverage",
+                "description": "Enable precise code coverage. Coverage data for JavaScript executed before enabling precise code coverage may be incomplete. Enabling prevents running optimized code and keeps execution count records alive.",
+                "experimental": true
+            },
+            {
+                "name": "stopPreciseCoverage",

[pfeldman, 2017/02/16 21:23:09]

How do I get a result?

[Yang, 2017/02/16 21:30:51]

By calling collectCoverage.

+                "description": "Disable precise code coverage. Disabling releases unnecessary execution count records and allows executing optimized code.",

[kozy, 2017/02/16 16:47:19]

Does this method reset counters?

[Yang, 2017/02/16 21:30:51]

No. Starting resets counters.

+                "experimental": true
+            },
+            {
+                "name": "collectCoverage",

[pfeldman, 2017/02/16 23:04:51]

Does it reset counters? I would expect both stopPreciseCoverage and
collectCoverage to reset counters. I'd also rename collectCoverage to
takeCoverage.

[Yang, 2017/02/17 05:35:54]

So you want incremental counts from last time coverage is taken? You'd need a
copy of the data if you want to accumulate the counts.

Since the non-precise count should affect performance less, and we are splitting
it off into a second method, I suggest we make that one less intrusive, i.e. not
clear invocation counts. Fadi, what's your take on this?

[pfeldman, 2017/02/17 17:59:39]

Right, Fadi's getBestEffortCoverage should not be resetting counters, only
startPreciseCoverage and takePreciseCoverage should be.

+                "returns": [
+                    { "name": "result", "type": "array", "items": { "$ref": "ScriptCoverage" }, "description": "Coverage data for the current isolate." }
+                ],
+                "description": "Collect coverage data for the current isolate.",

[pfeldman, 2017/02/16 21:23:09]

We should not expose non-precise coverage, while this could pull the coverage
data.

[Yang, 2017/02/16 21:30:51]

Fadi wanted exactly that though. He does not care about false negatives, but
affecting performance would be a no go.

[pfeldman, 2017/02/16 23:04:51]

We need to split best effort and precise coverage accessors then. Precise should
be started, stopped and polled. Best effort could be just queries. In fact, I'd
like to learn more about the best effort data - is it even good?

[Yang, 2017/02/17 05:35:54]

Data should be fairly good still, aside from functions that get garbage
collected. The count may differ from the actual count due to optimized code not
incrementing the invocation count, but a yes/no predicate can be made.

+                "experimental": true
             }
         ],
         "events": [
             {
                 "name": "executionContextCreated",
                 "parameters": [
                     { "name": "context", "$ref": "ExecutionContextDescription", "description": "A newly created execution contex." }
                 ],
                 "description": "Issued when new execution context is created."
             },
@@ skipping 640 matching lines @@
             {
                 "name": "heapStatsUpdate",
                 "description": "If heap objects tracking has been started then backend may send update for one or more fragments",
                 "parameters": [
                     { "name": "statsUpdate", "type": "array", "items": { "type": "integer" }, "description": "An array of triplets. Each triplet describes a fragment. The first integer is the fragment index, the second integer is a total count of objects for the fragment, the third integer is a total size of the objects for the fragment."}
                 ]
             }
         ]
     }]
 }