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

chrome/test/pyautolib/pyauto.py

Index: chrome/test/pyautolib/pyauto.py
diff --git a/chrome/test/pyautolib/pyauto.py b/chrome/test/pyautolib/pyauto.py
index 793dd95b33db6998dca35c275dd44bb104e626b8..8fe4a4b3f5618f368db903f0d77392e4a0f7cb29 100755
--- a/chrome/test/pyautolib/pyauto.py
+++ b/chrome/test/pyautolib/pyauto.py
@@ -2798,6 +2798,111 @@ class PyUITest(pyautolib.PyUITestBase, unittest.TestCase):
     return self._GetResultFromJSONRequest(cmd_dict, windex=windex,
                                           timeout=timeout)
 
+  def AddDomRaisedEventObserver(self, event_name='', tab_index=0, windex=0,
+                             frame_xpath=''):
+    """Adds a DomRaisedEventObserver associated with the AutomationEventQueue.
+
+    TODO(craigdh): Add documentation for raising an event once it has been

[Nirnimesh, 2012/02/28 09:13:09]

Move TODO's outside of the docstring, as comments.

[craigdh, 2012/02/28 22:42:56]

Done.

+    implemented.
+    TODO(craigdh): Add a corresponding method for extension views.
+
+    Args:
+      event_name: The raised event name to watch for. By default all raised
+                    events are observed.
+      tab_index: index of the tab.
+      windex: index of the window.
+      frame_xpath: XPath of the frame to execute the script.  Default is no
+                   frame. Example: '//frames[1]'.
+
+    Returns:
+      The id of the created observer, which can be used with GetQueuedEvent(id)
+      and RemoveEventObserver(id).
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'AddDomRaisedEventObserver',
+      'event_name': event_name,
+      'tab_index' : tab_index,
+      'windex' : windex,
+      'frame_xpath' : frame_xpath,
+    }
+    return self._GetResultFromJSONRequest(cmd_dict,
+                                          windex=windex)['observer_id']
+
+  def GetQueuedEvent(self, observer_id=-1, blocking=True, timeout=50000):

[Nirnimesh, 2012/02/28 09:13:09]

why 50 secs? Just use the default automation timeout.

[craigdh, 2012/02/28 22:42:56]

Done.

+    """Waits for an observed event to occur.
+
+    The returned event is removed from the Event Queue. If there is already a
+    matching event in the queue it is returned immediately, otherwise the call
+    blocks until a matching event occurs. If blocking is disabled and no
+    matching event is in the queue this function will immediately return None.
+
+    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.
+      timeout: Time to wait for a matching event, defaults to 50 seconds.
+
+    Returns:
+      Event response dictionary, or None if blocking is disabled and there is no
+      matching event in the queue.
+    SAMPLE:

[Nirnimesh, 2012/02/28 09:13:09]

Indent 2 spaces to the right

[craigdh, 2012/02/28 22:42:56]

Done.

+    { 'observer_id': 1,

[Nirnimesh, 2012/02/28 09:13:09]

same here

[craigdh, 2012/02/28 22:42:56]

Done.

+      'name': 'login completed',
+      'type': 'raised_event'}
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'GetQueuedEvent',
+      'observer_id' : observer_id,
+      'blocking' : blocking,
+    }
+    return self._GetResultFromJSONRequest(cmd_dict, windex=None,
+                                          timeout=timeout)
+
+  def RemoveEventObserver(self, observer_id):
+    """Removes an Event Observer from the AutomationEventQueue.
+
+    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)
+
+  def ClearQueuedEvents(self):
+    """Removes all events currently in the AutomationEventQueue.
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'ClearQueuedEvents',
+    }
+    return self._GetResultFromJSONRequest(cmd_dict, windex=None)
+
+  def ClearEventObservers(self):
+    """Removes all Event Observers associated with the AutomationEventQueue.
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'ClearEventObservers',
+    }
+    return self._GetResultFromJSONRequest(cmd_dict, windex=None)
+
   def ExecuteJavascript(self, js, tab_index=0, windex=0, frame_xpath=''):
     """Executes a script in the specified frame of a tab.