1#!/usr/bin/python2.4
2#
3#
4# Copyright 2008, The Android Open Source Project
5#
6# Licensed under the Apache License, Version 2.0 (the "License");
7# you may not use this file except in compliance with the License.
8# You may obtain a copy of the License at
9#
10#     http://www.apache.org/licenses/LICENSE-2.0
11#
12# Unless required by applicable law or agreed to in writing, software
13# distributed under the License is distributed on an "AS IS" BASIS,
14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15# See the License for the specific language governing permissions and
16# limitations under the License.
17
18"""Utilities for generating code coverage reports for Android tests."""
19
20# Python imports
21import glob
22import optparse
23import os
24
25# local imports
26import android_build
27import android_mk
28import coverage_target
29import coverage_targets
30import errors
31import logger
32import run_command
33
34
35class CoverageGenerator(object):
36  """Helper utility for obtaining code coverage results on Android.
37
38  Intended to simplify the process of building,running, and generating code
39  coverage results for a pre-defined set of tests and targets
40  """
41
42    # path to EMMA host jar, relative to Android build root
43  _EMMA_JAR = os.path.join("external", "emma", "lib", "emma.jar")
44  _TEST_COVERAGE_EXT = "ec"
45  # root path of generated coverage report files, relative to Android build root
46  _COVERAGE_REPORT_PATH = "emma"
47  _TARGET_DEF_FILE = "coverage_targets.xml"
48  _CORE_TARGET_PATH = os.path.join("development", "testrunner",
49                                   _TARGET_DEF_FILE)
50  # vendor glob file path patterns to tests, relative to android
51  # build root
52  _VENDOR_TARGET_PATH = os.path.join("vendor", "*", "tests", "testinfo",
53                                     _TARGET_DEF_FILE)
54
55  # path to root of target build intermediates
56  _TARGET_INTERMEDIATES_BASE_PATH = os.path.join("target", "common",
57                                                 "obj")
58
59  def __init__(self, adb_interface):
60    self._root_path = android_build.GetTop()
61    self._out_path = android_build.GetOut()
62    self._output_root_path = os.path.join(self._out_path,
63                                          self._COVERAGE_REPORT_PATH)
64    self._emma_jar_path = os.path.join(self._root_path, self._EMMA_JAR)
65    self._adb = adb_interface
66    self._targets_manifest = self._ReadTargets()
67
68  def ExtractReport(self,
69                    test_suite_name,
70                    target,
71                    device_coverage_path,
72                    output_path=None,
73                    test_qualifier=None):
74    """Extract runtime coverage data and generate code coverage report.
75
76    Assumes test has just been executed.
77    Args:
78      test_suite_name: name of TestSuite to generate coverage data for
79      target: the CoverageTarget to use as basis for coverage calculation
80      device_coverage_path: location of coverage file on device
81      output_path: path to place output files in. If None will use
82        <android_out_path>/<_COVERAGE_REPORT_PATH>/<target>/<test[-qualifier]>
83      test_qualifier: designates mode test was run with. e.g size=small.
84        If not None, this will be used to customize output_path as shown above.
85
86    Returns:
87      absolute file path string of generated html report file.
88    """
89    if output_path is None:
90      report_name = test_suite_name
91      if test_qualifier:
92        report_name = report_name + "-" + test_qualifier
93      output_path = os.path.join(self._out_path,
94                                 self._COVERAGE_REPORT_PATH,
95                                 target.GetName(),
96                                 report_name)
97
98    coverage_local_name = "%s.%s" % (report_name,
99                                     self._TEST_COVERAGE_EXT)
100    coverage_local_path = os.path.join(output_path,
101                                       coverage_local_name)
102    if self._adb.Pull(device_coverage_path, coverage_local_path):
103
104      report_path = os.path.join(output_path,
105                                 report_name)
106      return self._GenerateReport(report_path, coverage_local_path, [target],
107                                  do_src=True)
108    return None
109
110  def _GenerateReport(self, report_path, coverage_file_path, targets,
111                      do_src=True):
112    """Generate the code coverage report.
113
114    Args:
115      report_path: absolute file path of output file, without extension
116      coverage_file_path: absolute file path of code coverage result file
117      targets: list of CoverageTargets to use as base for code coverage
118          measurement.
119      do_src: True if generate coverage report with source linked in.
120          Note this will increase size of generated report.
121
122    Returns:
123      absolute file path to generated report file.
124    """
125    input_metadatas = self._GatherMetadatas(targets)
126
127    if do_src:
128      src_arg = self._GatherSrcs(targets)
129    else:
130      src_arg = ""
131
132    report_file = "%s.html" % report_path
133    cmd1 = ("java -cp %s emma report -r html -in %s %s %s " %
134            (self._emma_jar_path, coverage_file_path, input_metadatas, src_arg))
135    cmd2 = "-Dreport.html.out.file=%s" % report_file
136    self._RunCmd(cmd1 + cmd2)
137    return report_file
138
139  def _GatherMetadatas(self, targets):
140    """Builds the emma input metadata argument from provided targets.
141
142    Args:
143      targets: list of CoverageTargets
144
145    Returns:
146      input metadata argument string
147    """
148    input_metadatas = ""
149    for target in targets:
150      input_metadata = os.path.join(self._GetBuildIntermediatePath(target),
151                                    "coverage.em")
152      input_metadatas += " -in %s" % input_metadata
153    return input_metadatas
154
155  def _GetBuildIntermediatePath(self, target):
156    return os.path.join(
157        self._out_path, self._TARGET_INTERMEDIATES_BASE_PATH, target.GetType(),
158        "%s_intermediates" % target.GetName())
159
160  def _GatherSrcs(self, targets):
161    """Builds the emma input source path arguments from provided targets.
162
163    Args:
164      targets: list of CoverageTargets
165    Returns:
166      source path arguments string
167    """
168    src_list = []
169    for target in targets:
170      target_srcs = target.GetPaths()
171      for path in target_srcs:
172        src_list.append("-sp %s" %  os.path.join(self._root_path, path))
173    return " ".join(src_list)
174
175  def _MergeFiles(self, input_paths, dest_path):
176    """Merges a set of emma coverage files into a consolidated file.
177
178    Args:
179      input_paths: list of string absolute coverage file paths to merge
180      dest_path: absolute file path of destination file
181    """
182    input_list = []
183    for input_path in input_paths:
184      input_list.append("-in %s" % input_path)
185    input_args = " ".join(input_list)
186    self._RunCmd("java -cp %s emma merge %s -out %s" % (self._emma_jar_path,
187                                                        input_args, dest_path))
188
189  def _RunCmd(self, cmd):
190    """Runs and logs the given os command."""
191    run_command.RunCommand(cmd, return_output=False)
192
193  def _CombineTargetCoverage(self):
194    """Combines all target mode code coverage results.
195
196    Will find all code coverage data files in direct sub-directories of
197    self._output_root_path, and combine them into a single coverage report.
198    Generated report is placed at self._output_root_path/android.html
199    """
200    coverage_files = self._FindCoverageFiles(self._output_root_path)
201    combined_coverage = os.path.join(self._output_root_path,
202                                     "android.%s" % self._TEST_COVERAGE_EXT)
203    self._MergeFiles(coverage_files, combined_coverage)
204    report_path = os.path.join(self._output_root_path, "android")
205    # don't link to source, to limit file size
206    self._GenerateReport(report_path, combined_coverage,
207                         self._targets_manifest.GetTargets(), do_src=False)
208
209  def _CombineTestCoverage(self):
210    """Consolidates code coverage results for all target result directories."""
211    target_dirs = os.listdir(self._output_root_path)
212    for target_name in target_dirs:
213      output_path = os.path.join(self._output_root_path, target_name)
214      target = self._targets_manifest.GetTarget(target_name)
215      if os.path.isdir(output_path) and target is not None:
216        coverage_files = self._FindCoverageFiles(output_path)
217        combined_coverage = os.path.join(output_path, "%s.%s" %
218                                         (target_name, self._TEST_COVERAGE_EXT))
219        self._MergeFiles(coverage_files, combined_coverage)
220        report_path = os.path.join(output_path, target_name)
221        self._GenerateReport(report_path, combined_coverage, [target])
222      else:
223        logger.Log("%s is not a valid target directory, skipping" % output_path)
224
225  def _FindCoverageFiles(self, root_path):
226    """Finds all files in <root_path>/*/*.<_TEST_COVERAGE_EXT>.
227
228    Args:
229      root_path: absolute file path string to search from
230    Returns:
231      list of absolute file path strings of coverage files
232    """
233    file_pattern = os.path.join(root_path, "*", "*.%s" %
234                                self._TEST_COVERAGE_EXT)
235    coverage_files = glob.glob(file_pattern)
236    return coverage_files
237
238  def _ReadTargets(self):
239    """Parses the set of coverage target data.
240
241    Returns:
242       a CoverageTargets object that contains set of parsed targets.
243    Raises:
244       AbortError if a fatal error occurred when parsing the target files.
245    """
246    core_target_path = os.path.join(self._root_path, self._CORE_TARGET_PATH)
247    try:
248      targets = coverage_targets.CoverageTargets()
249      targets.Parse(core_target_path)
250      vendor_targets_pattern = os.path.join(self._root_path,
251                                            self._VENDOR_TARGET_PATH)
252      target_file_paths = glob.glob(vendor_targets_pattern)
253      for target_file_path in target_file_paths:
254        targets.Parse(target_file_path)
255      return targets
256    except errors.ParseError:
257      raise errors.AbortError
258
259  def TidyOutput(self):
260    """Runs tidy on all generated html files.
261
262    This is needed to the html files can be displayed cleanly on a web server.
263    Assumes tidy is on current PATH.
264    """
265    logger.Log("Tidying output files")
266    self._TidyDir(self._output_root_path)
267
268  def _TidyDir(self, dir_path):
269    """Recursively tidy all html files in given dir_path."""
270    html_file_pattern = os.path.join(dir_path, "*.html")
271    html_files_iter = glob.glob(html_file_pattern)
272    for html_file_path in html_files_iter:
273      os.system("tidy -m -errors -quiet %s" % html_file_path)
274    sub_dirs = os.listdir(dir_path)
275    for sub_dir_name in sub_dirs:
276      sub_dir_path = os.path.join(dir_path, sub_dir_name)
277      if os.path.isdir(sub_dir_path):
278        self._TidyDir(sub_dir_path)
279
280  def CombineCoverage(self):
281    """Create combined coverage reports for all targets and tests."""
282    self._CombineTestCoverage()
283    self._CombineTargetCoverage()
284
285  def GetCoverageTarget(self, name):
286    """Find the CoverageTarget for given name"""
287    target = self._targets_manifest.GetTarget(name)
288    if target is None:
289      msg = ["Error: test references undefined target %s." % name]
290      msg.append(" Ensure target is defined in %s" % self._TARGET_DEF_FILE)
291      raise errors.AbortError(msg)
292    return target
293
294  def GetCoverageTargetForPath(self, path):
295    """Find the CoverageTarget for given file system path"""
296    android_mk_path = os.path.join(path, "Android.mk")
297    if os.path.exists(android_mk_path):
298      android_mk_parser = android_mk.CreateAndroidMK(path)
299      target = coverage_target.CoverageTarget()
300      target.SetBuildPath(os.path.join(path, "src"))
301      target.SetName(android_mk_parser.GetVariable(android_mk_parser.PACKAGE_NAME))
302      target.SetType("APPS")
303      return target
304    else:
305      msg = "No Android.mk found at %s" % path
306      raise errors.AbortError(msg)
307
308
309def EnableCoverageBuild():
310  """Enable building an Android target with code coverage instrumentation."""
311  os.environ["EMMA_INSTRUMENT"] = "true"
312
313def Run():
314  """Does coverage operations based on command line args."""
315  # TODO: do we want to support combining coverage for a single target
316
317  try:
318    parser = optparse.OptionParser(usage="usage: %prog --combine-coverage")
319    parser.add_option(
320        "-c", "--combine-coverage", dest="combine_coverage", default=False,
321        action="store_true", help="Combine coverage results stored given "
322        "android root path")
323    parser.add_option(
324        "-t", "--tidy", dest="tidy", default=False, action="store_true",
325        help="Run tidy on all generated html files")
326
327    options, args = parser.parse_args()
328
329    coverage = CoverageGenerator(None)
330    if options.combine_coverage:
331      coverage.CombineCoverage()
332    if options.tidy:
333      coverage.TidyOutput()
334  except errors.AbortError:
335    logger.SilentLog("Exiting due to AbortError")
336
337if __name__ == "__main__":
338  Run()
339