emma_coverage_stats.py

#!/usr/bin/python
# Copyright 2015 The Chromium Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

"""Generates incremental code coverage reports for Java code in Chromium.

Usage:

  build/android/emma_coverage_stats.py -v --out <output file path> --emma-dir
    <EMMA file directory> --lines-for-coverage-file
    <path to file containing lines for coverage>

  Creates a JSON representation of the overall and file coverage stats and saves
  this information to the specified output file.
"""

import argparse
import collections
import json
import logging
import os
import re
import sys
from xml.etree import ElementTree

import devil_chromium
from devil.utils import run_tests_helper

NOT_EXECUTABLE = -1
NOT_COVERED = 0
COVERED = 1
PARTIALLY_COVERED = 2

# Coverage information about a single line of code.
LineCoverage = collections.namedtuple(
    'LineCoverage',
    ['lineno', 'source', 'covered_status', 'fractional_line_coverage'])


class _EmmaHtmlParser(object):
  """Encapsulates HTML file parsing operations.

  This class contains all operations related to parsing HTML files that were
  produced using the EMMA code coverage tool.

  Example HTML:

  Package links:
    <a href="_files/1.html">org.chromium.chrome</a>
    This is returned by the selector |XPATH_SELECT_PACKAGE_ELEMENTS|.

  Class links:
    <a href="1e.html">DoActivity.java</a>
    This is returned by the selector |XPATH_SELECT_CLASS_ELEMENTS|.

  Line coverage data:
    <tr class="p">
       <td class="l" title="78% line coverage (7 out of 9)">108</td>
       <td title="78% line coverage (7 out of 9 instructions)">
         if (index < 0 || index = mSelectors.size()) index = 0;</td>
    </tr>
    <tr>
       <td class="l">109</td>
       <td> </td>
    </tr>
    <tr class="c">
       <td class="l">110</td>
       <td>        if (mSelectors.get(index) != null) {</td>
    </tr>
    <tr class="z">
       <td class="l">111</td>
       <td>            for (int i = 0; i < mSelectors.size(); i++) {</td>
    </tr>
    Each <tr> element is returned by the selector |XPATH_SELECT_LOC|.

    We can parse this to get:
      1. Line number
      2. Line of source code
      3. Coverage status (c, z, or p)
      4. Fractional coverage value (% out of 100 if PARTIALLY_COVERED)
  """
  # Selector to match all <a> elements within the rows that are in the table
  # that displays all of the different packages.
  _XPATH_SELECT_PACKAGE_ELEMENTS = './/BODY/TABLE[4]/TR/TD/A'

  # Selector to match all <a> elements within the rows that are in the table
  # that displays all of the different classes within a package.
  _XPATH_SELECT_CLASS_ELEMENTS = './/BODY/TABLE[3]/TR/TD/A'

  # Selector to match all <tr> elements within the table containing Java source
  # code in an EMMA HTML file.
  _XPATH_SELECT_LOC = './/BODY/TABLE[4]/TR'

  # Children of HTML elements are represented as a list in ElementTree. These
  # constants represent list indices corresponding to relevant child elements.

  # Child 1 contains percentage covered for a line.
  _ELEMENT_PERCENT_COVERED = 1

  # Child 1 contains the original line of source code.
  _ELEMENT_CONTAINING_SOURCE_CODE = 1

  # Child 0 contains the line number.
  _ELEMENT_CONTAINING_LINENO = 0

  # Maps CSS class names to corresponding coverage constants.
  _CSS_TO_STATUS = {'c': COVERED, 'p': PARTIALLY_COVERED, 'z': NOT_COVERED}

  # UTF-8 no break space.
  _NO_BREAK_SPACE = '\xc2\xa0'

  def __init__(self, emma_file_base_dir):
    """Initializes _EmmaHtmlParser.

    Args:
      emma_file_base_dir: Path to the location where EMMA report files are
        stored. Should be where index.html is stored.
    """
    self._base_dir = emma_file_base_dir
    self._emma_files_path = os.path.join(self._base_dir, '_files')
    self._index_path = os.path.join(self._base_dir, 'index.html')

  def GetLineCoverage(self, emma_file_path):
    """Returns a list of LineCoverage objects for the given EMMA HTML file.

    Args:
      emma_file_path: String representing the path to the EMMA HTML file.

    Returns:
      A list of LineCoverage objects.
    """
    line_tr_elements = self._FindElements(
        emma_file_path, self._XPATH_SELECT_LOC)
    line_coverage = []
    for tr in line_tr_elements:
      # Get the coverage status.
      coverage_status = self._CSS_TO_STATUS.get(tr.get('CLASS'), NOT_EXECUTABLE)
      # Get the fractional coverage value.
      if coverage_status == PARTIALLY_COVERED:
        title_attribute = (tr[self._ELEMENT_PERCENT_COVERED].get('TITLE'))
        # Parse string that contains percent covered: "83% line coverage ...".
        percent_covered = title_attribute.split('%')[0]
        fractional_coverage = int(percent_covered) / 100.0
      else:
        fractional_coverage = 1.0

      # Get the line number.
      lineno_element = tr[self._ELEMENT_CONTAINING_LINENO]
      # Handles oddly formatted HTML (where there is an extra <a> tag).
      lineno = int(lineno_element.text or
                   lineno_element[self._ELEMENT_CONTAINING_LINENO].text)
      # Get the original line of Java source code.
      raw_source = tr[self._ELEMENT_CONTAINING_SOURCE_CODE].text
      utf8_source = raw_source.encode('UTF-8')
      source = utf8_source.replace(self._NO_BREAK_SPACE, ' ')

      line = LineCoverage(lineno, source, coverage_status, fractional_coverage)
      line_coverage.append(line)

    return line_coverage

  def GetPackageNameToEmmaFileDict(self):
    """Returns a dict mapping Java packages to EMMA HTML coverage files.

    Parses the EMMA index.html file to get a list of packages, then parses each
    package HTML file to get a list of classes for that package, and creates
    a dict with this info.

    Returns:
      A dict mapping string representation of Java packages (with class
        names appended) to the corresponding file paths of EMMA HTML files.
    """
    # These <a> elements contain each package name and the path of the file
    # where all classes within said package are listed.
    package_link_elements = self._FindElements(
        self._index_path, self._XPATH_SELECT_PACKAGE_ELEMENTS)
    # Maps file path of package directory (EMMA generated) to package name.
    # Example: emma_dir/f.html: org.chromium.chrome.
    package_links = {
      os.path.join(self._base_dir, link.attrib['HREF']): link.text
      for link in package_link_elements if 'HREF' in link.attrib
    }

    package_to_emma = {}
    for package_emma_file_path, package_name in package_links.iteritems():
      # These <a> elements contain each class name in the current package and
      # the path of the file where the coverage info is stored for each class.
      coverage_file_link_elements = self._FindElements(
          package_emma_file_path, self._XPATH_SELECT_CLASS_ELEMENTS)

      for class_name_element in coverage_file_link_elements:
        emma_coverage_file_path = os.path.join(
            self._emma_files_path, class_name_element.attrib['HREF'])
        full_package_name = '%s.%s' % (package_name, class_name_element.text)
        package_to_emma[full_package_name] = emma_coverage_file_path

    return package_to_emma

  # pylint: disable=no-self-use
  def _FindElements(self, file_path, xpath_selector):
    """Reads a HTML file and performs an XPath match.

    Args:
      file_path: String representing the path to the HTML file.
      xpath_selector: String representing xpath search pattern.

    Returns:
      A list of ElementTree.Elements matching the given XPath selector.
        Returns an empty list if there is no match.
    """
    with open(file_path) as f:
      file_contents = f.read().decode('ISO-8859-1').encode('UTF-8')
      root = ElementTree.fromstring(file_contents)
      return root.findall(xpath_selector)


class _EmmaCoverageStats(object):
  """Computes code coverage stats for Java code using the coverage tool EMMA.

  This class provides an API that allows users to capture absolute code coverage
  and code coverage on a subset of lines for each Java source file. Coverage
  reports are generated in JSON format.
  """
  # Regular expression to get package name from Java package statement.
  RE_PACKAGE_MATCH_GROUP = 'package'
  RE_PACKAGE = re.compile(r'package (?P<%s>[\w.]*);' % RE_PACKAGE_MATCH_GROUP)

  def __init__(self, emma_file_base_dir, files_for_coverage):
    """Initialize _EmmaCoverageStats.

    Args:
      emma_file_base_dir: String representing the path to the base directory
        where EMMA HTML coverage files are stored, i.e. parent of index.html.
      files_for_coverage: A list of Java source code file paths to get EMMA
        coverage for.
    """
    self._emma_parser = _EmmaHtmlParser(emma_file_base_dir)
    self._source_to_emma = self._GetSourceFileToEmmaFileDict(files_for_coverage)

  def GetCoverageDict(self, lines_for_coverage):
    """Returns a dict containing detailed coverage information.

    Gets detailed coverage stats for each file specified in the
    |lines_for_coverage| dict and the total incremental number of lines covered
    and executable for all files in |lines_for_coverage|.

    Args:
      lines_for_coverage: A dict mapping Java source file paths to lists of line
        numbers.

    Returns:
      A dict containing coverage stats for the given dict of files and lines.
        Contains absolute coverage stats for each file, coverage stats for each
        file's lines specified in |lines_for_coverage|, line by line coverage
        for each file, and overall coverage stats for the lines specified in
        |lines_for_coverage|.
    """
    file_coverage = {}
    for file_path, line_numbers in lines_for_coverage.iteritems():
      file_coverage_dict = self.GetCoverageDictForFile(file_path, line_numbers)
      if file_coverage_dict:
        file_coverage[file_path] = file_coverage_dict
      else:
        logging.warning(
            'No code coverage data for %s, skipping.', file_path)

    covered_statuses = [s['incremental'] for s in file_coverage.itervalues()]
    num_covered_lines = sum(s['covered'] for s in covered_statuses)
    num_total_lines = sum(s['total'] for s in covered_statuses)
    return {
      'files': file_coverage,
      'patch': {
        'incremental': {
          'covered': num_covered_lines,
          'total': num_total_lines
        }
      }
    }

  def GetCoverageDictForFile(self, file_path, line_numbers):
    """Returns a dict containing detailed coverage info for the given file.

    Args:
      file_path: The path to the Java source file that we want to create the
        coverage dict for.
      line_numbers: A list of integer line numbers to retrieve additional stats
        for.

    Returns:
      A dict containing absolute, incremental, and line by line coverage for
        a file.
    """
    if file_path not in self._source_to_emma:
      return None
    emma_file = self._source_to_emma[file_path]
    total_line_coverage = self._emma_parser.GetLineCoverage(emma_file)
    incremental_line_coverage = [line for line in total_line_coverage
                                 if line.lineno in line_numbers]
    line_by_line_coverage = [
      {
        'line': line.source,
        'coverage': line.covered_status,
        'changed': line.lineno in line_numbers,
        'fractional_coverage': line.fractional_line_coverage,
      }
      for line in total_line_coverage
    ]
    total_covered_lines, total_lines = (
        self.GetSummaryStatsForLines(total_line_coverage))
    incremental_covered_lines, incremental_total_lines = (
        self.GetSummaryStatsForLines(incremental_line_coverage))

    file_coverage_stats = {
      'absolute': {
        'covered': total_covered_lines,
        'total': total_lines
      },
      'incremental': {
        'covered': incremental_covered_lines,
        'total': incremental_total_lines
      },
      'source': line_by_line_coverage,
    }
    return file_coverage_stats

  # pylint: disable=no-self-use
  def GetSummaryStatsForLines(self, line_coverage):
    """Gets summary stats for a given list of LineCoverage objects.

    Args:
      line_coverage: A list of LineCoverage objects.

    Returns:
      A tuple containing the number of lines that are covered and the total
        number of lines that are executable, respectively
    """
    partially_covered_sum = 0
    covered_status_totals = {COVERED: 0, NOT_COVERED: 0, PARTIALLY_COVERED: 0}
    for line in line_coverage:
      status = line.covered_status
      if status == NOT_EXECUTABLE:
        continue
      covered_status_totals[status] += 1
      if status == PARTIALLY_COVERED:
        partially_covered_sum += line.fractional_line_coverage

    total_covered = covered_status_totals[COVERED] + partially_covered_sum
    total_lines = sum(covered_status_totals.values())
    return total_covered, total_lines

  def _GetSourceFileToEmmaFileDict(self, files):
    """Gets a dict used to correlate Java source files with EMMA HTML files.

    This method gathers the information needed to correlate EMMA HTML
    files with Java source files. EMMA XML and plain text reports do not provide
    line by line coverage data, so HTML reports must be used instead.
    Unfortunately, the HTML files that are created are given garbage names
    (i.e 1.html) so we need to manually correlate EMMA HTML files
    with the original Java source files.

    Args:
      files: A list of file names for which coverage information is desired.

    Returns:
      A dict mapping Java source file paths to EMMA HTML file paths.
    """
    # Maps Java source file paths to package names.
    # Example: /usr/code/file.java -> org.chromium.file.java.
    source_to_package = {}
    for file_path in files:
      package = self.GetPackageNameFromFile(file_path)
      if package:
        source_to_package[file_path] = package
      else:
        logging.warning("Skipping %s because it doesn\'t have a package "
                        "statement.", file_path)

    # Maps package names to EMMA report HTML files.
    # Example: org.chromium.file.java -> out/coverage/1a.html.
    package_to_emma = self._emma_parser.GetPackageNameToEmmaFileDict()
    # Finally, we have a dict mapping Java file paths to EMMA report files.
    # Example: /usr/code/file.java -> out/coverage/1a.html.
    source_to_emma = {source: package_to_emma[package]
                      for source, package in source_to_package.iteritems()
                      if package in package_to_emma}
    return source_to_emma

  @staticmethod
  def NeedsCoverage(file_path):
    """Checks to see if the file needs to be analyzed for code coverage.

    Args:
      file_path: A string representing path to the file.

    Returns:
      True for Java files that exist, False for all others.
    """
    if os.path.splitext(file_path)[1] == '.java' and os.path.exists(file_path):
      return True
    else:
      logging.info('Skipping file %s, cannot compute code coverage.', file_path)
      return False

  @staticmethod
  def GetPackageNameFromFile(file_path):
    """Gets the full package name including the file name for a given file path.

    Args:
      file_path: String representing the path to the Java source file.

    Returns:
      A string representing the full package name with file name appended or
        None if there is no package statement in the file.
    """
    with open(file_path) as f:
      file_content = f.read()
      package_match = re.search(_EmmaCoverageStats.RE_PACKAGE, file_content)
      if package_match:
        package = package_match.group(_EmmaCoverageStats.RE_PACKAGE_MATCH_GROUP)
        file_name = os.path.basename(file_path)
        return '%s.%s' % (package, file_name)
      else:
        return None


def GenerateCoverageReport(line_coverage_file, out_file_path, coverage_dir):
  """Generates a coverage report for a given set of lines.

  Writes the results of the coverage analysis to the file specified by
  |out_file_path|.

  Args:
    line_coverage_file: The path to a file which contains a dict mapping file
      names to lists of line numbers. Example: {file1: [1, 2, 3], ...} means
      that we should compute coverage information on lines 1 - 3 for file1.
    out_file_path: A string representing the location to write the JSON report.
    coverage_dir: A string representing the file path where the EMMA
      HTML coverage files are located (i.e. folder where index.html is located).
  """
  with open(line_coverage_file) as f:
    potential_files_for_coverage = json.load(f)

  files_for_coverage = {f: lines
                        for f, lines in potential_files_for_coverage.iteritems()
                        if _EmmaCoverageStats.NeedsCoverage(f)}

  coverage_results = {}
  if files_for_coverage:
    code_coverage = _EmmaCoverageStats(coverage_dir, files_for_coverage.keys())
    coverage_results = code_coverage.GetCoverageDict(files_for_coverage)
  else:
    logging.info('No Java files requiring coverage were included in %s.',
                 line_coverage_file)

  with open(out_file_path, 'w+') as out_status_file:
    json.dump(coverage_results, out_status_file)


def main():
  argparser = argparse.ArgumentParser()
  argparser.add_argument('--out', required=True, type=str,
                         help='Report output file path.')
  argparser.add_argument('--emma-dir', required=True, type=str,
                         help='EMMA HTML report directory.')
  argparser.add_argument('--lines-for-coverage-file', required=True, type=str,
                         help='File containing a JSON object. Should contain a '
                         'dict mapping file names to lists of line numbers of '
                         'code for which coverage information is desired.')
  argparser.add_argument('-v', '--verbose', action='count',
                         help='Print verbose log information.')
  args = argparser.parse_args()
  run_tests_helper.SetLogLevel(args.verbose)
  devil_chromium.Initialize()
  GenerateCoverageReport(args.lines_for_coverage_file, args.out, args.emma_dir)


if __name__ == '__main__':
  sys.exit(main())