Implementation of AutomationEventQueue and associated framework to support generic non-blocking aut…

chrome/test/pyautolib/pyauto.py

 #!/usr/bin/env python
 # Copyright (c) 2012 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.
 
 """PyAuto: Python Interface to Chromium's Automation Proxy.
 
 PyAuto uses swig to expose Automation Proxy interfaces to Python.
 For complete documentation on the functionality available,
 run pydoc on this file.
@@ skipping 2780 matching lines @@
       'command': 'FindInPage',
       'tab_index' : tab_index,
       'search_string' : search_string,
       'forward' : forward,
       'match_case' : match_case,
       'find_next' : find_next,
     }
     return self._GetResultFromJSONRequest(cmd_dict, windex=windex,
                                           timeout=timeout)
 
+  def ObserveRaisedEvents(self, event_name="", tab_index=0, windex=0,

[dennis_jeffrey, 2012/02/23 19:26:36]

prefer single quotes over double quotes

[dennis_jeffrey, 2012/02/23 19:26:36]

Would a name like "GetEventObserver" be better here?

[craigdh, 2012/02/24 01:30:02]

Perhaps "AddRaisedEventObserver" as there are going to be a few different types
of event observers in the future. The Raised Event Observer is just the simplest
type (the DOM Mutation Event Observer is next and will build on the Raised Event
Observer).

+                          frame_xpath=''):
+    """Creates a raised event observer and associates it with the event queue.
+
+    TODO(craigdh): Describe the correct method of raising an event once it has
+    been implemented.
+
+    Args:
+      'event_name': The raised event name to watch for. By default all raised
+                    events are observed.
+      'windex' : windex,
+      'tab_index' : tab_index,
+      'frame_xpath' : frame_xpath,

[dennis_jeffrey, 2012/02/23 19:26:36]

for the above 3 argument descriptions, we should have a brief sentence
describing the argument, rather than just repeating the argument name.

[craigdh, 2012/02/24 01:30:02]

Copy-Paste error. Done.

+
+    Returns:
+      The id of the created observer, which can be used with GetEvent(id) and
+      RemoveEventObserver(id).
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'ObserveRaisedEvents',
+      'event_name': event_name,
+      'windex' : windex,
+      'tab_index' : tab_index,
+      'frame_xpath' : frame_xpath,
+    }
+    return self._GetResultFromJSONRequest(cmd_dict,
+                                          timeout=50000).get('observer_id')

[dennis_jeffrey, 2012/02/23 19:26:36]

should we use "self.large_test_timeout_ms()" instead of hard-coding 50 seconds
here?

[dennis_jeffrey, 2012/02/23 19:26:36]

will the call to get() here ever return None? (I think that happens in the case
that the specified key doesn't exist in the dictionary).  If so, we should
mention this in the docstring above.  If not, maybe we could just do
['observer_id'] instead of .get('observer_id')

[craigdh, 2012/02/24 01:30:02]

Good point. It should never return None.

[craigdh, 2012/02/24 01:30:02]

I wasn't aware that existed. Done.

+
+  def GetEvent(self, observer_id=-1, blocking=True):

[dennis_jeffrey, 2012/02/23 19:26:36]

If this function gets an event, is that event removed from the event queue?

[craigdh, 2012/02/24 01:30:02]

Yes. Clarified this in the comments.

+    """Waits for a registered event to occur.
+
+    Args:
+      'observer_id': The id of the observer to wait for, matches any event by
+                     default.
+      'blocking': If True waits until there is a matching event in the queue,
+                  if False and there is no event waiting in the queue returns
+                  None immediately.
+
+    Returns:
+      Event response.

[dennis_jeffrey, 2012/02/23 19:26:36]

is this a string or a number?

[craigdh, 2012/02/24 01:30:02]

Neither, it is a dictionary. Added an example.

+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'GetEvent',
+      'observer_id' : observer_id,
+      'blocking' : blocking,
+    }
+    return self._GetResultFromJSONRequest(cmd_dict, windex=None, timeout=50000)
+
+  def RemoveEventObserver(self, observer_id):
+    """Removes an Event Observer from the event queue.
+
+    Args:
+      'observer_id': The id of the observer to remove.
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'RemoveEventObserver',
+      'observer_id' : observer_id,
+    }
+    return self._GetResultFromJSONRequest(cmd_dict, windex=None, timeout=50000)
+
+  def ClearEvents(self):
+    """Removes all events currently in the event queue.
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'ClearEvents',
+    }
+    return self._GetResultFromJSONRequest(cmd_dict, windex=None, timeout=50000)
+
+  def ClearEventObservers(self):

[dennis_jeffrey, 2012/02/23 19:26:36]

Would it make sense to have pyauto automatically call this at the end of each
executed test, or is that not necessary? (same with function ClearEvents above).

[craigdh, 2012/02/24 01:30:02]

So long as PyAuto always restarts the browser before each test the queue will be
cleared then. Is there any case in which PyAuto does not restart the browser
before a test?

+    """Removes all Event Observers currently associated with the event queue.
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'ClearEventObservers',
+    }
+    return self._GetResultFromJSONRequest(cmd_dict, windex=None, timeout=50000)
+
   def ExecuteJavascript(self, js, tab_index=0, windex=0, frame_xpath=''):
     """Executes a script in the specified frame of a tab.
 
     By default, execute the script in the top frame of the first tab in the
     first window. The invoked javascript function must send a result back via
     the domAutomationController.send function, or this function will never
     return.
 
     Args:
       js: script to be executed.
@@ skipping 2213 matching lines @@
     successful = result.wasSuccessful()
     if not successful:
       pyauto_tests_file = os.path.join(self.TestsDir(), self._tests_filename)
       print >>sys.stderr, 'Tests can be disabled by editing %s. ' \
                           'Ref: %s' % (pyauto_tests_file, _PYAUTO_DOC_URL)
     sys.exit(not successful)
 
 
 if __name__ == '__main__':
   Main()