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..220234ed9414c23e2c542e2771822b957a0b70a3 100755
--- a/chrome/test/pyautolib/pyauto.py
+++ b/chrome/test/pyautolib/pyauto.py
@@ -2798,6 +2798,97 @@ class PyUITest(pyautolib.PyUITestBase, unittest.TestCase):
     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.