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..0b60ded157ed244af9fdbd26b28a3d8e8b250c7a 100755
--- a/chrome/test/pyautolib/pyauto.py
+++ b/chrome/test/pyautolib/pyauto.py
@@ -2798,6 +2798,108 @@ class PyUITest(pyautolib.PyUITestBase, unittest.TestCase):
     return self._GetResultFromJSONRequest(cmd_dict, windex=windex,
                                           timeout=timeout)
 
+  def AddRaisedEventObserver(self, event_name='', tab_index=0, windex=0,

[Nirnimesh, 2012/02/24 23:18:09]

It's not clear to the end-user what 'Raised event' is, and when to use it.

Rename (maybe add 'app') and explain in the docstring.

[craigdh, 2012/02/27 22:43:38]

Rename done.

I have the usage description written up in a CL I will be submitting after this
one, as in this CL the usage is hacky and I don't want to document functionality
here that hasn't been introduced yet (as noted in apptest.py).

+                                frame_xpath=''):

[frankf, 2012/02/24 22:05:07]

alignment issue

[craigdh, 2012/02/24 23:19:33]

Done.

+    """Creates a raised event observer and associates it with the event queue.
+

[Nirnimesh, 2012/02/24 23:18:09]

Add a TODO to add a corresponding method for extension views too (ala
ExecuteJavascript)

+    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

[frankf, 2012/02/24 22:05:07]

why is the arg in quotes?

[craigdh, 2012/02/24 23:19:33]

Because it was copy-pasted from the cmd_dict and I missed them. Fixed.

+                    events are observed.
+      windex: index of the window.

[frankf, 2012/02/24 22:05:07]

follow the order of function signature.

[craigdh, 2012/02/24 23:19:33]

Done.

+      tab_index: index of the tab.
+      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 GetEvent(id) and
+      RemoveEventObserver(id).
+
+    Raises:
+      pyauto_errors.JSONInterfaceError if the automation call returns an error.
+    """
+    cmd_dict = {
+      'command': 'AddRaisedEventObserver',
+      'event_name': event_name,
+      'windex' : windex,
+      'tab_index' : tab_index,

[frankf, 2012/02/24 22:05:07]

same with ordering here.

[craigdh, 2012/02/24 23:19:33]

Done.

+      'frame_xpath' : frame_xpath,
+    }
+    return self._GetResultFromJSONRequest(
+        cmd_dict, timeout=self.large_test_timeout_ms())['observer_id']
+
+  def GetEvent(self, observer_id=-1, blocking=True):

[Nirnimesh, 2012/02/24 23:18:09]

add 'app' somewhere in the name.

[craigdh, 2012/02/27 22:43:38]

I don't want to limit the naming to just apps, so I'm renaming this
"GetQueuedEvent".

+    """Waits for an event to occur.

[Nirnimesh, 2012/02/24 23:18:09]

Waits for one of the observed events to occur

[craigdh, 2012/02/27 22:43:38]

Done.

+
+    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

[frankf, 2012/02/24 22:05:07]

again, why quotes?

[craigdh, 2012/02/24 23:19:33]

Done.

+                     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 dictionary, or None if blocking is disabled and there is no
+      matching event in the queue.
+    SAMPLE:
+    { 'observer_id': 1,
+      'name': 'login completed',
+      'type': 'raised_event'}
+
+    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)

[frankf, 2012/02/24 22:05:07]

if feel like it, define 50000 as a constant like large_test_timeout_ms. 

[Nirnimesh, 2012/02/24 23:18:09]

why 50s?

Leave it as the default, but provide a way to pass it from param to GetEvent()
since there might be app functions that'd require a timeout of > default
automation timeout

[craigdh, 2012/02/24 23:19:33]

Oops, I meant to do self.large_test_timeout_ms(). Done.

+
+  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.

[Nirnimesh, 2012/02/24 23:18:09]

event -> app event
Repeat everywhere

[craigdh, 2012/02/27 22:43:38]

There is no inherent requirement that they have anything to do with webapps, but
I will clarify the naming.

+
+    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):
+    """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)

[Nirnimesh, 2012/02/24 23:18:09]

why override this timeout?

[craigdh, 2012/02/27 22:43:38]

No reason. Removed.

+
   def ExecuteJavascript(self, js, tab_index=0, windex=0, frame_xpath=''):
     """Executes a script in the specified frame of a tab.