src/tools/telemetry/telemetry/page/page_measurement.py

   1 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 # Use of this source code is governed by a BSD-style license that can be
   3 # found in the LICENSE file.
   4
   5 from telemetry.page import page_test
   6
   7
   8 class MeasurementFailure(page_test.Failure):
   9   """Exception that can be thrown from MeasurePage to indicate an undesired but
  10   designed-for problem."""
  11   pass
  12
  13
  14 class PageMeasurement(page_test.PageTest):
  15   """Glue code for running a measurement across a set of pages.
  16
  17   To use this, subclass from the measurement and override MeasurePage. For
  18   example:
  19
  20      class BodyChildElementMeasurement(PageMeasurement):
  21         def MeasurePage(self, page, tab, results):
  22            body_child_count = tab.EvaluateJavaScript(
  23                'document.body.children.length')
  24            results.Add('body_children', 'count', body_child_count)
  25
  26      if __name__ == '__main__':
  27          page_measurement.Main(BodyChildElementMeasurement())
  28
  29   To add test-specific options:
  30
  31      class BodyChildElementMeasurement(PageMeasurement):
  32         def AddCommandLineOptions(parser):
  33            parser.add_option('--element', action='store', default='body')
  34
  35         def MeasurePage(self, page, tab, results):
  36            body_child_count = tab.EvaluateJavaScript(
  37               'document.querySelector('%s').children.length')
  38            results.Add('children', 'count', child_count)
  39   """
  40   def __init__(self,
  41                action_name_to_run='',
  42                needs_browser_restart_after_each_run=False,
  43                discard_first_result=False,
  44                clear_cache_before_each_run=False):
  45     super(PageMeasurement, self).__init__(
  46       '_RunTest',
  47       action_name_to_run,
  48       needs_browser_restart_after_each_run,
  49       discard_first_result,
  50       clear_cache_before_each_run)
  51
  52   def _RunTest(self, page, tab, results):
  53     results.WillMeasurePage(page)
  54     self.MeasurePage(page, tab, results)
  55     results.DidMeasurePage()
  56
  57   @property
  58   def results_are_the_same_on_every_page(self):
  59     """By default, measurements are assumed to output the same values for every
  60     page. This allows incremental output, for example in CSV. If, however, the
  61     measurement discovers what values it can report as it goes, and those values
  62     may vary from page to page, you need to override this function and return
  63     False. Output will not appear in this mode until the entire pageset has
  64     run."""
  65     return True
  66
  67   def MeasurePage(self, page, tab, results):
  68     """Override to actually measure the page's performance.
  69
  70     page is a page_set.Page
  71     tab is an instance of telemetry.core.Tab
  72
  73     Should call results.Add(name, units, value) for each result, or raise an
  74     exception on failure. The name and units of each Add() call must be
  75     the same across all iterations. The name 'url' must not be used.
  76
  77     Prefer field names that are in accordance with python variable style. E.g.
  78     field_name.
  79
  80     Put together:
  81
  82        def MeasurePage(self, page, tab, results):
  83          res = tab.EvaluateJavaScript('2+2')
  84          if res != 4:
  85            raise Exception('Oh, wow.')
  86          results.Add('two_plus_two', 'count', res)
  87     """
  88     raise NotImplementedError()