1# Copyright 2015 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 5import re 6 7from telemetry.story import shared_state as shared_state_module 8 9_next_story_id = 0 10 11 12class Story(object): 13 """A class styled on unittest.TestCase for creating story tests. 14 15 Tests should override Run to maybe start the application and perform actions 16 on it. To share state between different tests, one can define a 17 shared_state which contains hooks that will be called before and 18 after mutiple stories run and in between runs. 19 20 Args: 21 shared_state_class: subclass of telemetry.story.shared_state.SharedState. 22 name: string name of this story that can be used for identifying this story 23 in results output. 24 labels: A list or set of string labels that are used for filtering. See 25 story.story_filter for more information. 26 is_local: If True, the story does not require network. 27 grouping_keys: A dict of grouping keys that will be added to values computed 28 on this story. 29 """ 30 31 def __init__(self, shared_state_class, name='', labels=None, 32 is_local=False, make_javascript_deterministic=True, 33 grouping_keys=None): 34 """ 35 Args: 36 make_javascript_deterministic: Whether JavaScript performed on 37 the page is made deterministic across multiple runs. This 38 requires that the web content is served via Web Page Replay 39 to take effect. This setting does not affect stories containing no web 40 content or where the HTTP MIME type is not text/html.See also: 41 _InjectScripts method in third_party/web-page-replay/httpclient.py. 42 """ 43 assert issubclass(shared_state_class, 44 shared_state_module.SharedState) 45 self._shared_state_class = shared_state_class 46 self._name = name 47 global _next_story_id 48 self._id = _next_story_id 49 _next_story_id += 1 50 if labels is None: 51 labels = set([]) 52 elif isinstance(labels, list): 53 labels = set(labels) 54 else: 55 assert isinstance(labels, set) 56 self._labels = labels 57 self._is_local = is_local 58 self._make_javascript_deterministic = make_javascript_deterministic 59 if grouping_keys is None: 60 grouping_keys = {} 61 else: 62 assert isinstance(grouping_keys, dict) 63 self._grouping_keys = grouping_keys 64 65 def Run(self, shared_state): 66 """Execute the interactions with the applications and/or platforms.""" 67 raise NotImplementedError 68 69 @property 70 def labels(self): 71 return self._labels 72 73 @property 74 def shared_state_class(self): 75 return self._shared_state_class 76 77 @property 78 def id(self): 79 return self._id 80 81 @property 82 def name(self): 83 return self._name 84 85 @property 86 def grouping_keys(self): 87 return self._grouping_keys 88 89 90 def AsDict(self): 91 """Converts a story object to a dict suitable for JSON output.""" 92 d = { 93 'id': self._id, 94 } 95 if self._name: 96 d['name'] = self._name 97 return d 98 99 @property 100 def file_safe_name(self): 101 """A version of display_name that's safe to use as a filename. 102 103 The default implementation sanitizes special characters with underscores, 104 but it's okay to override it with a more specific implementation in 105 subclasses. 106 """ 107 # This fail-safe implementation is safe for subclasses to override. 108 return re.sub('[^a-zA-Z0-9]', '_', self.display_name) 109 110 @property 111 def display_name(self): 112 if self.name: 113 return self.name 114 else: 115 return self.__class__.__name__ 116 117 @property 118 def is_local(self): 119 """Returns True iff this story does not require network.""" 120 return self._is_local 121 122 @property 123 def serving_dir(self): 124 """Returns the absolute path to a directory with hash files to data that 125 should be updated from cloud storage, or None if no files need to be 126 updated. 127 """ 128 return None 129 130 @property 131 def make_javascript_deterministic(self): 132 return self._make_javascript_deterministic 133