content/public/test/browser_test_utils.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CONTENT_PUBLIC_TEST_BROWSER_TEST_UTILS_H_
   6 #define CONTENT_PUBLIC_TEST_BROWSER_TEST_UTILS_H_
   7
   8 #include <queue>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/callback_forward.h"
  13 #include "base/compiler_specific.h"
  14 #include "base/files/scoped_temp_dir.h"
  15 #include "base/memory/ref_counted.h"
  16 #include "base/process/process.h"
  17 #include "base/strings/string16.h"
  18 #include "content/public/browser/notification_observer.h"
  19 #include "content/public/browser/notification_registrar.h"
  20 #include "content/public/browser/render_process_host_observer.h"
  21 #include "content/public/browser/web_contents_observer.h"
  22 #include "third_party/WebKit/public/web/WebInputEvent.h"
  23 #include "ui/events/keycodes/keyboard_codes.h"
  24 #include "url/gurl.h"
  25
  26 #if defined(OS_WIN)
  27 #include "base/win/scoped_handle.h"
  28 #endif
  29
  30 class CommandLine;
  31
  32 namespace base {
  33 class RunLoop;
  34 }
  35
  36 namespace gfx {
  37 class Point;
  38 }
  39
  40 // A collections of functions designed for use with content_browsertests and
  41 // browser_tests.
  42 // TO BE CLEAR: any function here must work against both binaries. If it only
  43 // works with browser_tests, it should be in chrome\test\base\ui_test_utils.h.
  44 // If it only works with content_browsertests, it should be in
  45 // content\test\content_browser_test_utils.h.
  46
  47 namespace content {
  48
  49 class BrowserContext;
  50 class MessageLoopRunner;
  51 class RenderViewHost;
  52 class WebContents;
  53
  54 // Generate a URL for a file path including a query string.
  55 GURL GetFileUrlWithQuery(const base::FilePath& path,
  56                          const std::string& query_string);
  57
  58 // Waits for a load stop for the specified |web_contents|'s controller, if the
  59 // tab is currently web_contents.  Otherwise returns immediately.
  60 void WaitForLoadStop(WebContents* web_contents);
  61
  62 // Causes the specified web_contents to crash. Blocks until it is crashed.
  63 void CrashTab(WebContents* web_contents);
  64
  65 // Simulates clicking at the center of the given tab asynchronously; modifiers
  66 // may contain bits from WebInputEvent::Modifiers.
  67 void SimulateMouseClick(WebContents* web_contents,
  68                         int modifiers,
  69                         blink::WebMouseEvent::Button button);
  70
  71 // Simulates clicking at the point |point| of the given tab asynchronously;
  72 // modifiers may contain bits from WebInputEvent::Modifiers.
  73 void SimulateMouseClickAt(WebContents* web_contents,
  74                           int modifiers,
  75                           blink::WebMouseEvent::Button button,
  76                           const gfx::Point& point);
  77
  78 // Simulates asynchronously a mouse enter/move/leave event.
  79 void SimulateMouseEvent(WebContents* web_contents,
  80                         blink::WebInputEvent::Type type,
  81                         const gfx::Point& point);
  82
  83 // Sends a key press asynchronously.
  84 // The native code of the key event will be set to InvalidNativeKeycode().
  85 // |key_code| alone is good enough for scenarios that only need the char
  86 // value represented by a key event and not the physical key on the keyboard
  87 // or the keyboard layout.
  88 // For scenarios such as chromoting that need the native code,
  89 // SimulateKeyPressWithCode should be used.
  90 void SimulateKeyPress(WebContents* web_contents,
  91                       ui::KeyboardCode key_code,
  92                       bool control,
  93                       bool shift,
  94                       bool alt,
  95                       bool command);
  96
  97 // Sends a key press asynchronously.
  98 // |code| specifies the UIEvents (aka: DOM4Events) value of the key:
  99 // https://dvcs.w3.org/hg/d4e/raw-file/tip/source_respec.htm
 100 // The native code of the key event will be set based on |code|.
 101 // See ui/base/keycodes/vi usb_keycode_map.h for mappings between |code|
 102 // and the native code.
 103 // Examples of the various codes:
 104 //   key_code: VKEY_A
 105 //   code: "KeyA"
 106 //   native key code: 0x001e (for Windows).
 107 //   native key code: 0x0026 (for Linux).
 108 void SimulateKeyPressWithCode(WebContents* web_contents,
 109                               ui::KeyboardCode key_code,
 110                               const char* code,
 111                               bool control,
 112                               bool shift,
 113                               bool alt,
 114                               bool command);
 115
 116 // Allow ExecuteScript* methods to target either a WebContents or a
 117 // RenderViewHost.  Targetting a WebContents means executing script in the
 118 // RenderViewHost returned by WebContents::GetRenderViewHost(), which is the
 119 // "current" RenderViewHost.  Pass a specific RenderViewHost to target, for
 120 // example, a "swapped-out" RenderViewHost.
 121 namespace internal {
 122 class ToRenderViewHost {
 123  public:
 124   ToRenderViewHost(WebContents* web_contents);
 125   ToRenderViewHost(RenderViewHost* render_view_host);
 126
 127   RenderViewHost* render_view_host() const { return render_view_host_; }
 128
 129  private:
 130   RenderViewHost* render_view_host_;
 131 };
 132 }  // namespace internal
 133
 134 // Executes the passed |script| in the frame pointed to by |frame_xpath| (use
 135 // empty string for main frame).  The |script| should not invoke
 136 // domAutomationController.send(); otherwise, your test will hang or be flaky.
 137 // If you want to extract a result, use one of the below functions.
 138 // Returns true on success.
 139 bool ExecuteScriptInFrame(const internal::ToRenderViewHost& adapter,
 140                           const std::string& frame_xpath,
 141                           const std::string& script) WARN_UNUSED_RESULT;
 142
 143 // The following methods executes the passed |script| in the frame pointed to by
 144 // |frame_xpath| (use empty string for main frame) and sets |result| to the
 145 // value passed to "window.domAutomationController.send" by the executed script.
 146 // They return true on success, false if the script execution failed or did not
 147 // evaluate to the expected type.
 148 bool ExecuteScriptInFrameAndExtractInt(
 149     const internal::ToRenderViewHost& adapter,
 150     const std::string& frame_xpath,
 151     const std::string& script,
 152     int* result) WARN_UNUSED_RESULT;
 153 bool ExecuteScriptInFrameAndExtractBool(
 154     const internal::ToRenderViewHost& adapter,
 155     const std::string& frame_xpath,
 156     const std::string& script,
 157     bool* result) WARN_UNUSED_RESULT;
 158 bool ExecuteScriptInFrameAndExtractString(
 159     const internal::ToRenderViewHost& adapter,
 160     const std::string& frame_xpath,
 161     const std::string& script,
 162     std::string* result) WARN_UNUSED_RESULT;
 163
 164 // Top-frame script execution helpers (a.k.a., the common case):
 165 bool ExecuteScript(const internal::ToRenderViewHost& adapter,
 166                    const std::string& script) WARN_UNUSED_RESULT;
 167 bool ExecuteScriptAndExtractInt(const internal::ToRenderViewHost& adapter,
 168                                 const std::string& script,
 169                                 int* result) WARN_UNUSED_RESULT;
 170 bool ExecuteScriptAndExtractBool(const internal::ToRenderViewHost& adapter,
 171                                  const std::string& script,
 172                                  bool* result) WARN_UNUSED_RESULT;
 173 bool ExecuteScriptAndExtractString(const internal::ToRenderViewHost& adapter,
 174                                    const std::string& script,
 175                                    std::string* result) WARN_UNUSED_RESULT;
 176
 177 // Executes the WebUI resource test runner injecting each resource ID in
 178 // |js_resource_ids| prior to executing the tests.
 179 //
 180 // Returns true if tests ran successfully, false otherwise.
 181 bool ExecuteWebUIResourceTest(const internal::ToRenderViewHost& adapter,
 182                               const std::vector<int>& js_resource_ids);
 183
 184 // Returns the cookies for the given url.
 185 std::string GetCookies(BrowserContext* browser_context, const GURL& url);
 186
 187 // Sets a cookie for the given url. Returns true on success.
 188 bool SetCookie(BrowserContext* browser_context,
 189                const GURL& url,
 190                const std::string& value);
 191
 192 // Watches title changes on a WebContents, blocking until an expected title is
 193 // set.
 194 class TitleWatcher : public WebContentsObserver {
 195  public:
 196   // |web_contents| must be non-NULL and needs to stay alive for the
 197   // entire lifetime of |this|. |expected_title| is the title that |this|
 198   // will wait for.
 199   TitleWatcher(WebContents* web_contents,
 200                const base::string16& expected_title);
 201   virtual ~TitleWatcher();
 202
 203   // Adds another title to watch for.
 204   void AlsoWaitForTitle(const base::string16& expected_title);
 205
 206   // Waits until the title matches either expected_title or one of the titles
 207   // added with AlsoWaitForTitle. Returns the value of the most recently
 208   // observed matching title.
 209   const base::string16& WaitAndGetTitle() WARN_UNUSED_RESULT;
 210
 211  private:
 212   // Overridden WebContentsObserver methods.
 213   virtual void DidStopLoading(RenderViewHost* render_view_host) OVERRIDE;
 214   virtual void TitleWasSet(NavigationEntry* entry, bool explicit_set) OVERRIDE;
 215
 216   void TestTitle();
 217
 218   std::vector<base::string16> expected_titles_;
 219   scoped_refptr<MessageLoopRunner> message_loop_runner_;
 220
 221   // The most recently observed expected title, if any.
 222   base::string16 observed_title_;
 223
 224   DISALLOW_COPY_AND_ASSIGN(TitleWatcher);
 225 };
 226
 227 // Watches a WebContents and blocks until it is destroyed.
 228 class WebContentsDestroyedWatcher : public WebContentsObserver {
 229  public:
 230   explicit WebContentsDestroyedWatcher(WebContents* web_contents);
 231   virtual ~WebContentsDestroyedWatcher();
 232
 233   // Waits until the WebContents is destroyed.
 234   void Wait();
 235
 236  private:
 237   // Overridden WebContentsObserver methods.
 238   virtual void WebContentsDestroyed(WebContents* web_contents) OVERRIDE;
 239
 240   scoped_refptr<MessageLoopRunner> message_loop_runner_;
 241
 242   DISALLOW_COPY_AND_ASSIGN(WebContentsDestroyedWatcher);
 243 };
 244
 245 // Watches a RenderProcessHost and waits for specified destruction events.
 246 class RenderProcessHostWatcher : public RenderProcessHostObserver {
 247  public:
 248   enum WatchType {
 249     WATCH_FOR_PROCESS_EXIT,
 250     WATCH_FOR_HOST_DESTRUCTION
 251   };
 252
 253   RenderProcessHostWatcher(RenderProcessHost* render_process_host,
 254                            WatchType type);
 255   // Waits for the render process that contains the specified web contents.
 256   RenderProcessHostWatcher(WebContents* web_contents, WatchType type);
 257   virtual ~RenderProcessHostWatcher();
 258
 259   // Waits until the renderer process exits.
 260   void Wait();
 261
 262  private:
 263   // Overridden RenderProcessHost::LifecycleObserver methods.
 264   virtual void RenderProcessExited(RenderProcessHost* host,
 265                                    base::ProcessHandle handle,
 266                                    base::TerminationStatus status,
 267                                    int exit_code) OVERRIDE;
 268   virtual void RenderProcessHostDestroyed(RenderProcessHost* host) OVERRIDE;
 269
 270   RenderProcessHost* render_process_host_;
 271   WatchType type_;
 272
 273   scoped_refptr<MessageLoopRunner> message_loop_runner_;
 274
 275   DISALLOW_COPY_AND_ASSIGN(RenderProcessHostWatcher);
 276 };
 277
 278 // Watches for responses from the DOMAutomationController and keeps them in a
 279 // queue. Useful for waiting for a message to be received.
 280 class DOMMessageQueue : public NotificationObserver {
 281  public:
 282   // Constructs a DOMMessageQueue and begins listening for messages from the
 283   // DOMAutomationController. Do not construct this until the browser has
 284   // started.
 285   DOMMessageQueue();
 286   virtual ~DOMMessageQueue();
 287
 288   // Removes all messages in the message queue.
 289   void ClearQueue();
 290
 291   // Wait for the next message to arrive. |message| will be set to the next
 292   // message, if not null. Returns true on success.
 293   bool WaitForMessage(std::string* message) WARN_UNUSED_RESULT;
 294
 295   // Overridden NotificationObserver methods.
 296   virtual void Observe(int type,
 297                        const NotificationSource& source,
 298                        const NotificationDetails& details) OVERRIDE;
 299
 300  private:
 301   NotificationRegistrar registrar_;
 302   std::queue<std::string> message_queue_;
 303   bool waiting_for_message_;
 304   scoped_refptr<MessageLoopRunner> message_loop_runner_;
 305
 306   DISALLOW_COPY_AND_ASSIGN(DOMMessageQueue);
 307 };
 308
 309 }  // namespace content
 310
 311 #endif  // CONTENT_PUBLIC_TEST_BROWSER_TEST_UTILS_H_