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.
5 #ifndef CONTENT_PUBLIC_TEST_BROWSER_TEST_UTILS_H_
6 #define CONTENT_PUBLIC_TEST_BROWSER_TEST_UTILS_H_
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"
27 #include "base/win/scoped_handle.h"
38 // A collections of functions designed for use with content_browsertests and
40 // TO BE CLEAR: any function here must work against both binaries. If it only
41 // works with browser_tests, it should be in chrome\test\base\ui_test_utils.h.
42 // If it only works with content_browsertests, it should be in
43 // content\test\content_browser_test_utils.h.
48 class MessageLoopRunner;
52 // Generate a URL for a file path including a query string.
53 GURL GetFileUrlWithQuery(const base::FilePath& path,
54 const std::string& query_string);
56 // Waits for a load stop for the specified |web_contents|'s controller, if the
57 // tab is currently web_contents. Otherwise returns immediately.
58 void WaitForLoadStop(WebContents* web_contents);
61 // If WebContent's view is currently being resized, this will wait for the ack
62 // from the renderer that the resize is complete and for the
63 // WindowEventDispatcher to release the pointer moves. If there's no resize in
64 // progress, the method will return right away.
65 void WaitForResizeComplete(WebContents* web_contents);
68 // Causes the specified web_contents to crash. Blocks until it is crashed.
69 void CrashTab(WebContents* web_contents);
71 // Simulates clicking at the center of the given tab asynchronously; modifiers
72 // may contain bits from WebInputEvent::Modifiers.
73 void SimulateMouseClick(WebContents* web_contents,
75 blink::WebMouseEvent::Button button);
77 // Simulates clicking at the point |point| of the given tab asynchronously;
78 // modifiers may contain bits from WebInputEvent::Modifiers.
79 void SimulateMouseClickAt(WebContents* web_contents,
81 blink::WebMouseEvent::Button button,
82 const gfx::Point& point);
84 // Simulates asynchronously a mouse enter/move/leave event.
85 void SimulateMouseEvent(WebContents* web_contents,
86 blink::WebInputEvent::Type type,
87 const gfx::Point& point);
89 // Taps the screen at |point|.
90 void SimulateTapAt(WebContents* web_contents, const gfx::Point& point);
92 // Sends a key press asynchronously.
93 // The native code of the key event will be set to InvalidNativeKeycode().
94 // |key_code| alone is good enough for scenarios that only need the char
95 // value represented by a key event and not the physical key on the keyboard
96 // or the keyboard layout.
97 // For scenarios such as chromoting that need the native code,
98 // SimulateKeyPressWithCode should be used.
99 void SimulateKeyPress(WebContents* web_contents,
100 ui::KeyboardCode key_code,
106 // Sends a key press asynchronously.
107 // |code| specifies the UIEvents (aka: DOM4Events) value of the key:
108 // https://dvcs.w3.org/hg/d4e/raw-file/tip/source_respec.htm
109 // The native code of the key event will be set based on |code|.
110 // See ui/base/keycodes/vi usb_keycode_map.h for mappings between |code|
111 // and the native code.
112 // Examples of the various codes:
115 // native key code: 0x001e (for Windows).
116 // native key code: 0x0026 (for Linux).
117 void SimulateKeyPressWithCode(WebContents* web_contents,
118 ui::KeyboardCode key_code,
126 // Allow ExecuteScript* methods to target either a WebContents or a
127 // RenderFrameHost. Targetting a WebContents means executing the script in the
128 // RenderFrameHost returned by WebContents::GetMainFrame(), which is the
129 // main frame. Pass a specific RenderFrameHost to target it.
130 class ToRenderFrameHost {
132 ToRenderFrameHost(WebContents* web_contents);
133 ToRenderFrameHost(RenderViewHost* render_view_host);
134 ToRenderFrameHost(RenderFrameHost* render_frame_host);
136 RenderFrameHost* render_frame_host() const { return render_frame_host_; }
139 RenderFrameHost* render_frame_host_;
141 } // namespace internal
143 // Executes the passed |script| in the specified frame. The |script| should not
144 // invoke domAutomationController.send(); otherwise, your test will hang or be
145 // flaky. If you want to extract a result, use one of the below functions.
146 // Returns true on success.
147 bool ExecuteScript(const internal::ToRenderFrameHost& adapter,
148 const std::string& script) WARN_UNUSED_RESULT;
150 // The following methods executes the passed |script| in the specified frame and
151 // sets |result| to the value passed to "window.domAutomationController.send" by
152 // the executed script. They return true on success, false if the script
153 // execution failed or did not evaluate to the expected type.
154 bool ExecuteScriptAndExtractInt(const internal::ToRenderFrameHost& adapter,
155 const std::string& script,
156 int* result) WARN_UNUSED_RESULT;
157 bool ExecuteScriptAndExtractBool(const internal::ToRenderFrameHost& adapter,
158 const std::string& script,
159 bool* result) WARN_UNUSED_RESULT;
160 bool ExecuteScriptAndExtractString(const internal::ToRenderFrameHost& adapter,
161 const std::string& script,
162 std::string* result) WARN_UNUSED_RESULT;
164 // Walks the frame tree of the specified WebContents and returns the sole frame
165 // that matches the specified predicate function. This function will DCHECK if
166 // no frames match the specified predicate, or if more than one frame matches.
167 RenderFrameHost* FrameMatchingPredicate(
168 WebContents* web_contents,
169 const base::Callback<bool(RenderFrameHost*)>& predicate);
171 // Predicates for use with FrameMatchingPredicate.
172 bool FrameMatchesName(const std::string& name, RenderFrameHost* frame);
173 bool FrameIsChildOfMainFrame(RenderFrameHost* frame);
174 bool FrameHasSourceUrl(const GURL& url, RenderFrameHost* frame);
176 // Executes the WebUI resource test runner injecting each resource ID in
177 // |js_resource_ids| prior to executing the tests.
179 // Returns true if tests ran successfully, false otherwise.
180 bool ExecuteWebUIResourceTest(WebContents* web_contents,
181 const std::vector<int>& js_resource_ids);
183 // Returns the cookies for the given url.
184 std::string GetCookies(BrowserContext* browser_context, const GURL& url);
186 // Sets a cookie for the given url. Returns true on success.
187 bool SetCookie(BrowserContext* browser_context,
189 const std::string& value);
191 // Fetch the histograms data from other processes. This should be called after
192 // the test code has been executed but before performing assertions.
193 void FetchHistogramsFromChildProcesses();
195 // Watches title changes on a WebContents, blocking until an expected title is
197 class TitleWatcher : public WebContentsObserver {
199 // |web_contents| must be non-NULL and needs to stay alive for the
200 // entire lifetime of |this|. |expected_title| is the title that |this|
202 TitleWatcher(WebContents* web_contents,
203 const base::string16& expected_title);
204 virtual ~TitleWatcher();
206 // Adds another title to watch for.
207 void AlsoWaitForTitle(const base::string16& expected_title);
209 // Waits until the title matches either expected_title or one of the titles
210 // added with AlsoWaitForTitle. Returns the value of the most recently
211 // observed matching title.
212 const base::string16& WaitAndGetTitle() WARN_UNUSED_RESULT;
215 // Overridden WebContentsObserver methods.
216 virtual void DidStopLoading(RenderViewHost* render_view_host) OVERRIDE;
217 virtual void TitleWasSet(NavigationEntry* entry, bool explicit_set) OVERRIDE;
221 std::vector<base::string16> expected_titles_;
222 scoped_refptr<MessageLoopRunner> message_loop_runner_;
224 // The most recently observed expected title, if any.
225 base::string16 observed_title_;
227 DISALLOW_COPY_AND_ASSIGN(TitleWatcher);
230 // Watches a WebContents and blocks until it is destroyed.
231 class WebContentsDestroyedWatcher : public WebContentsObserver {
233 explicit WebContentsDestroyedWatcher(WebContents* web_contents);
234 virtual ~WebContentsDestroyedWatcher();
236 // Waits until the WebContents is destroyed.
240 // Overridden WebContentsObserver methods.
241 virtual void WebContentsDestroyed() OVERRIDE;
243 scoped_refptr<MessageLoopRunner> message_loop_runner_;
245 DISALLOW_COPY_AND_ASSIGN(WebContentsDestroyedWatcher);
248 // Watches a RenderProcessHost and waits for specified destruction events.
249 class RenderProcessHostWatcher : public RenderProcessHostObserver {
252 WATCH_FOR_PROCESS_EXIT,
253 WATCH_FOR_HOST_DESTRUCTION
256 RenderProcessHostWatcher(RenderProcessHost* render_process_host,
258 // Waits for the render process that contains the specified web contents.
259 RenderProcessHostWatcher(WebContents* web_contents, WatchType type);
260 virtual ~RenderProcessHostWatcher();
262 // Waits until the renderer process exits.
266 // Overridden RenderProcessHost::LifecycleObserver methods.
267 virtual void RenderProcessExited(RenderProcessHost* host,
268 base::ProcessHandle handle,
269 base::TerminationStatus status,
270 int exit_code) OVERRIDE;
271 virtual void RenderProcessHostDestroyed(RenderProcessHost* host) OVERRIDE;
273 RenderProcessHost* render_process_host_;
276 scoped_refptr<MessageLoopRunner> message_loop_runner_;
278 DISALLOW_COPY_AND_ASSIGN(RenderProcessHostWatcher);
281 // Watches for responses from the DOMAutomationController and keeps them in a
282 // queue. Useful for waiting for a message to be received.
283 class DOMMessageQueue : public NotificationObserver {
285 // Constructs a DOMMessageQueue and begins listening for messages from the
286 // DOMAutomationController. Do not construct this until the browser has
289 virtual ~DOMMessageQueue();
291 // Removes all messages in the message queue.
294 // Wait for the next message to arrive. |message| will be set to the next
295 // message. Returns true on success.
296 bool WaitForMessage(std::string* message) WARN_UNUSED_RESULT;
298 // Overridden NotificationObserver methods.
299 virtual void Observe(int type,
300 const NotificationSource& source,
301 const NotificationDetails& details) OVERRIDE;
304 NotificationRegistrar registrar_;
305 std::queue<std::string> message_queue_;
306 scoped_refptr<MessageLoopRunner> message_loop_runner_;
308 DISALLOW_COPY_AND_ASSIGN(DOMMessageQueue);
311 } // namespace content
313 #endif // CONTENT_PUBLIC_TEST_BROWSER_TEST_UTILS_H_