Implement AutomationNode.querySelector().

chrome/common/extensions/api/automation.idl

 // Copyright 2014 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.
 
 // The <code>chrome.automation</code> API allows developers to access the
 // automation (accessibility) tree for the browser. The tree resembles the DOM
 // tree, but only exposes the <em>semantic</em> structure of a page. It can be
 // used to programmatically interact with a page by examining names, roles, and
 // states, listening for events, and performing actions on nodes.
 [nocompile] namespace automation {
@@ skipping 202 matching lines @@
     visited
   };
 
   dictionary Rect {
     long left;
     long top;
     long width;
     long height;
   };
 
+  // The parameters for a <code>query</code>.
+  dictionary QueryInfo {
+    DOMString? querySelector;
+  };
+
+  // Called when the result for a <code>query</code> is available.
+  callback QueryCallback = void(AutomationNode node);
+
   // An event in the Automation tree.
   [nocompile, noinline_doc] dictionary AutomationEvent {
     // The $(ref:automation.AutomationNode) to which the event was targeted.
     AutomationNode target;
 
     // The type of the event.
     EventType type;
 
     // Stops this event from further processing except for any remaining
     // listeners on $(ref:AutomationEvent.target).
@@ skipping 52 matching lines @@
     // Sets selection within a text field.
     static void setSelection(long startIndex, long endIndex);
 
     // Adds a listener for the given event type and event phase.
     static void addEventListener(
         EventType eventType, AutomationListener listener, boolean capture);
 
     // Removes a listener for the given event type and event phase.
     static void removeEventListener(
         EventType eventType, AutomationListener listener, boolean capture);
+
+    // Gets the first node in this node's subtree which matches the given CSS
+    // selector and is within the same DOM context.
+    //
+    // If this node doesn't correspond directly with an HTML node in the DOM,
+    // querySelector will be run on this node's nearest HTML node ancestor. Note
+    // that this may result in the query returning a node which is not an
+    // ancestor of this node.

[dmazzoni, 2014/10/30 23:32:42]

nit: ancestor -> descendant

[aboxhall, 2014/10/31 20:32:22]

Oops, done.

+    //
+    // If the selector matches a node which doesn't directly correspond to an
+    // automation node (for example an element within an ARIA widget, where the

[dmazzoni, 2014/10/30 23:32:42]

Your example doesn't make sense, we don't remove nodes from aria widgets from
the automation tree. The simplest example would be nodes that are hidden or not
displayed - they'll be returned by querySelector but won't have an automation
node.

[aboxhall, 2014/10/31 20:32:22]

The are ignoredForAccessibility and don't end up in the tree, as per my test,
but I added comments about hidden elements as well. I can remove the ARIA widget
example if I've missed something...

+    // ARIA widget forms one node of the automation tree), this will return the
+    // nearest ancestor which does correspond to an automation node.
+    static void querySelector(DOMString selector, QueryCallback callback);
   };
 
   // Called when the <code>AutomationRootNode</code> for the page is available.
   callback RootCallback = void(AutomationRootNode rootNode);
 
   // The root node of the automation tree for a single frame or desktop.
   // This may be:
   // <ul>
   //   <li> The desktop
   //   <li> The top frame of a page
@@ skipping 25 matching lines @@
     // tree with a placeholder root node; listen for the "loadComplete" event to
     // get a notification that the tree has fully loaded (the previous root node
     // reference will stop working at or before this point).
     [nocompile] static void getTree(optional long tabId, RootCallback callback);
 
     // Get the automation tree for the whole desktop which consists of all on
     // screen views. Note this API is currently only supported on Chrome OS.
     [nocompile] static void getDesktop(RootCallback callback);
   };
 };