getSourceReport method

Future<SourceReport> getSourceReport(
  1. String isolateId,
  2. List<String> reports, {
  3. String? scriptId,
  4. int? tokenPos,
  5. int? endTokenPos,
  6. bool? forceCompile,
  7. bool? reportLines,
  8. List<String>? libraryFilters,
  9. List<String>? librariesAlreadyCompiled,
})

The getSourceReport RPC is used to generate a set of reports tied to source locations in an isolate.

The reports parameter is used to specify which reports should be generated. The reports parameter is a list, which allows multiple reports to be generated simultaneously from a consistent isolate state. The reports parameter is allowed to be empty (this might be used to force compilation of a particular subrange of some script).

The available report kinds are:

report kind meaning
Coverage Provide code coverage information
PossibleBreakpoints Provide a list of token positions which correspond
to possible breakpoints.

The scriptId parameter is used to restrict the report to a particular script. When analyzing a particular script, either or both of the tokenPos and endTokenPos parameters may be provided to restrict the analysis to a subrange of a script (for example, these can be used to restrict the report to the range of a particular class or function).

If the scriptId parameter is not provided then the reports are generated for all loaded scripts and the tokenPos and endTokenPos parameters are disallowed.

The forceCompilation parameter can be used to force compilation of all functions in the range of the report. Forcing compilation can cause a compilation error, which could terminate the running Dart program. If this parameter is not provided, it is considered to have the value false.

The reportLines parameter changes the token positions in SourceReportRange.possibleBreakpoints and SourceReportCoverage to be line numbers. This is designed to reduce the number of RPCs that need to be performed in the case that the client is only interested in line numbers. If this parameter is not provided, it is considered to have the value false.

The libraryFilters parameter is intended to be used when gathering coverage for the whole isolate. If it is provided, the SourceReport will only contain results from scripts with URIs that start with one of the filter strings. For example, pass ["package:foo/"] to only include scripts from the foo package.

The librariesAlreadyCompiled parameter overrides the forceCompilation parameter on a per-library basis, setting it to false for any libary in this list. This is useful for cases where multiple getSourceReport RPCs are sent with forceCompilation enabled, to avoid recompiling the same libraries repeatedly. To use this parameter, enable forceCompilation, cache the results of each getSourceReport RPC, and pass all the libraries mentioned in the SourceReport to subsequent RPCs in the librariesAlreadyCompiled.

If isolateId refers to an isolate which has exited, then the Collected Sentinel is returned.

See SourceReport.

This method will throw a SentinelException in the case a Sentinel is returned.

Implementation

Future<SourceReport> getSourceReport(
  String isolateId,
  /*List<SourceReportKind>*/ List<String> reports, {
  String? scriptId,
  int? tokenPos,
  int? endTokenPos,
  bool? forceCompile,
  bool? reportLines,
  List<String>? libraryFilters,
  List<String>? librariesAlreadyCompiled,
}) =>
    _call('getSourceReport', {
      'isolateId': isolateId,
      'reports': reports,
      if (scriptId != null) 'scriptId': scriptId,
      if (tokenPos != null) 'tokenPos': tokenPos,
      if (endTokenPos != null) 'endTokenPos': endTokenPos,
      if (forceCompile != null) 'forceCompile': forceCompile,
      if (reportLines != null) 'reportLines': reportLines,
      if (libraryFilters != null) 'libraryFilters': libraryFilters,
      if (librariesAlreadyCompiled != null)
        'librariesAlreadyCompiled': librariesAlreadyCompiled,
    });