blob: 91d6023038a6342b2304dbec493477d9bfb17d57 [file] [log] [blame]
// Copyright (c) 2011 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.
// Swig Interface for PyAuto.
// PyAuto makes the Automation Proxy interface available in Python
// Running swig as:
// swig -python -c++ chrome/test/pyautolib/pyautolib.i
// would generate, pyautolib_wrap.cxx
// When adding a new class or method, make sure you specify the doc string using
// %feature("docstring", "doc string goes here") NODENAME;
// and attach it to your node (class or method). This doc string will be
// copied over in the generated python classes/methods.
%module(docstring="Python interface to Automation Proxy.") pyautolib
%feature("autodoc", "1");
%include <std_wstring.i>
%include <std_string.i>
%include "chrome/test/pyautolib/argc_argv.i"
// NOTE: All files included in this file should also be listed under
// pyautolib_sources in chrome_tests.gypi.
// Headers that can be swigged directly.
%include "chrome/app/chrome_command_ids.h"
%include "chrome/app/chrome_dll_resource.h"
%include "chrome/common/automation_constants.h"
%include "chrome/common/pref_names.h"
#include "chrome/common/automation_constants.h"
#include "chrome/common/pref_names.h"
#include "chrome/test/automation/browser_proxy.h"
#include "chrome/test/automation/tab_proxy.h"
#include "chrome/test/pyautolib/pyautolib.h"
#include "net/test/test_server.h"
// Handle type uint32 conversions as int
%apply int { uint32 };
// scoped_refptr
template <class T>
class scoped_refptr {
scoped_refptr(T* p);
T* get() const;
T* operator->() const;
%template(scoped_refptr__BrowserProxy) scoped_refptr<BrowserProxy>;
%template(scoped_refptr__TabProxy) scoped_refptr<TabProxy>;
%feature("docstring", "Represent a URL. Call spec() to get the string.") GURL;
class GURL {
explicit GURL(const std::string& url_string);
%feature("docstring", "Get the string representation.") spec;
const std::string& spec() const;
// FilePath
"Represent a file path. Call value() to get the string.") FilePath;
class FilePath {
%feature("docstring", "Get the string representation.") value;
#ifdef SWIGWIN
typedef std::wstring StringType;
typedef std::string StringType;
#endif // SWIGWIN
const StringType& value() const;
%feature("docstring", "Construct an empty FilePath from a string.")
explicit FilePath(const StringType& path);
// BrowserProxy
%feature("docstring", "Proxy handle to a browser window.") BrowserProxy;
%nodefaultctor BrowserProxy;
%nodefaultdtor BrowserProxy;
class BrowserProxy {
%feature("docstring", "Activate the tab at the given zero-based index")
bool ActivateTab(int tab_index);
%feature("docstring", "Activate the browser's window and bring it to front.")
bool BringToFront();
%feature("docstring", "Get proxy to the tab at the given zero-based index")
scoped_refptr<TabProxy> GetTab(int tab_index) const;
// TabProxy
%feature("docstring", "Proxy handle to a tab.") TabProxy;
%nodefaultctor TabProxy;
%nodefaultdtor TabProxy;
class TabProxy {
// Navigation
%feature("docstring", "Navigates to a given GURL. "
"Blocks until the navigation completes. ") NavigateToURL;
AutomationMsg_NavigationResponseValues NavigateToURL(const GURL& url);
%feature("docstring", "Navigates to a given GURL. Blocks until the given "
"number of navigations complete.")
const GURL& url, int number_of_navigations);
%feature("docstring", "Navigates to a given GURL asynchronously. "
"Does not wait for the navigation to complete, or even begin; "
"Use NavigateToURL() if you want to wait.") NavigateToURLAsync;
bool TabProxy::NavigateToURLAsync(const GURL& url);
%feature("docstring", "Equivalent to hitting the Back button. "
"Blocks until navigation completes.") GoBack;
AutomationMsg_NavigationResponseValues GoBack();
%feature("docstring", "Equivalent to hitting the Forward button. "
"Blocks until navigation completes.") GoForward;
AutomationMsg_NavigationResponseValues GoForward();
%feature("docstring", "Equivalent to hitting the Reload button. "
"Blocks until navigation completes.") Reload;
AutomationMsg_NavigationResponseValues Reload();
%feature("docstring", "Closes the tab. Supply True to wait "
"until the tab has closed, else it'll wait only until the call "
"has been initiated. Be careful while closing the last tab "
"since it might close the browser.") Close;
bool Close();
bool Close(bool wait_until_closed);
%feature("docstring", "Blocks until tab is completely restored.")
bool WaitForTabToBeRestored(uint32 timeout_ms);
// HTTP Auth
"Checks if this tab has a login prompt waiting for auth. This will be "
"true if a navigation results in a login prompt, and if an attempted "
"login fails. "
"Note that this is only valid if you've done a navigation on this same "
"object; different TabProxy objects can refer to the same Tab. Calls "
"that can set this are NavigateToURL, GoBack, and GoForward. ")
bool NeedsAuth() const;
%feature("docstring", "Supply authentication to a login prompt. "
"Blocks until navigation completes or another login prompt appears "
"in the case of failed auth.") SetAuth;
bool SetAuth(const std::wstring& username, const std::wstring& password);
%feature("docstring", "Cancel authentication to a login prompt. ")
bool CancelAuth();
class PyUITestSuiteBase {
%feature("docstring", "Create the suite.") PyUITestSuiteBase;
PyUITestSuiteBase(int argc, char** argv);
virtual ~PyUITestSuiteBase();
%feature("docstring", "Initialize from the path to browser dir.")
void InitializeWithPath(const FilePath& browser_dir);
%feature("docstring", "Set chrome source root path, used in some tests")
void SetCrSourceRoot(const FilePath& path);
class PyUITestBase {
PyUITestBase(bool clear_profile, std::wstring homepage);
%feature("docstring", "Initialize the entire setup. Should be called "
"before launching the browser. For internal use.") Initialize;
void Initialize(const FilePath& browser_dir);
%feature("docstring", "Appends a command-line switch (with associated value "
"if given) to the list of switches to be passed to the browser "
"upon launch. Should be called before launching the browser. "
"For internal use only.")
void AppendBrowserLaunchSwitch(const char* name);
void AppendBrowserLaunchSwitch(const char* name, const char* value);
void UseNamedChannelID(const std::string& named_channel_id);
"Fires up the browser and opens a window.") SetUp;
virtual void SetUp();
"Closes all windows and destroys the browser.") TearDown;
virtual void TearDown();
%feature("docstring", "Timeout (in milli secs) for an action. "
"This value is also used as default for the WaitUntil() method.")
int action_max_timeout_ms() const;
%feature("docstring", "Get the timeout (in milli secs) for an automation "
"call") action_timeout_ms;
int action_timeout_ms();
%feature("docstring", "Set the timeout (in milli secs) for an automation "
"call. This is an internal method. Do not use this directly. "
"Use ActionTimeoutChanger instead")
void set_action_timeout_ms(int timeout);
%feature("docstring", "Timeout (in milli secs) for large tests.")
int large_test_timeout_ms() const;
%feature("docstring", "Launches the browser and IPC testing server.")
void LaunchBrowserAndServer();
%feature("docstring", "Closes the browser and IPC testing server.")
void CloseBrowserAndServer();
%feature("docstring", "Determine if the profile is set to be cleared on "
"next startup.") get_clear_profile;
bool get_clear_profile() const;
%feature("docstring", "If False, sets the flag so that the profile is "
"not cleared on next startup. Useful for persisting profile "
"across restarts. By default the state is True, to clear profile.")
void set_clear_profile(bool clear_profile);
// Navigation Methods
%feature("docstring", "Navigate to the given url in the given tab and given "
"window (or active tab in first window if indexes not given). "
"Note that this method also activates the corresponding tab/window "
"if it's not active already. Blocks until page has loaded.")
void NavigateToURL(const char* url_string);
void NavigateToURL(const char* url_string, int window_index);
void NavigateToURL(const char* url_string, int window_index, int tab_index);
%feature("docstring", "Reload the active tab in the given window (or first "
"window if index not given). Blocks until page has reloaded.")
void ReloadActiveTab(int window_index = 0);
// BrowserProxy methods
%feature("docstring", "Apply the accelerator with given id "
"(IDC_BACK, IDC_NEWTAB ...) to the given or first window. "
"The list can be found at chrome/app/chrome_dll_resource.h. "
"Note that this method just schedules the accelerator, but does "
"not wait for it to actually finish doing anything."
"Returns True on success.")
bool ApplyAccelerator(int id, int window_index=0);
%feature("docstring", "Like ApplyAccelerator, except that it waits for "
"the command to execute.") RunCommand;
bool RunCommand(int browser_command, int window_index = 0);
// Get/fetch properties
"Get the path to download directory.") GetDownloadDirectory;
FilePath GetDownloadDirectory();
%feature("docstring", "Get the path to profile directory.") user_data_dir;
FilePath user_data_dir() const;
%feature("docstring", "Set download shelf visibility for the given or "
"first browser window.") SetDownloadShelfVisible;
void SetDownloadShelfVisible(bool is_visible, int window_index=0);
%feature("docstring", "Determine if the download shelf is visible in the "
"given or first browser window.") IsDownloadShelfVisible;
bool IsDownloadShelfVisible(int window_index=0);
%feature("docstring", "Determine if the bookmark bar is visible. "
"If the NTP is visible, only return true if attached "
"(to the chrome).") GetBookmarkBarVisibility;
bool GetBookmarkBarVisibility();
%feature("docstring", "Wait for the bookmark bar animation to complete. "
"|wait_for_open| specifies which kind of change we wait for.")
bool WaitForBookmarkBarVisibilityChange(bool wait_for_open);
%feature("docstring", "Get the bookmarks as a JSON string. Internal method.")
std::string _GetBookmarksAsJSON();
%feature("docstring", "Add a bookmark folder with the given index in the parent."
" |title| is the title/name of the folder.") AddBookmarkGroup;
bool AddBookmarkGroup(std::wstring parent_id, int index, std::wstring title);
%feature("docstring", "Add a bookmark with the given title and URL.") AddBookmarkURL;
bool AddBookmarkURL(std::wstring parent_id, int index,
std::wstring title, const std::wstring url);
%feature("docstring", "Move a bookmark to a new parent.") ReparentBookmark;
bool ReparentBookmark(std::wstring id, std::wstring new_parent_id, int index);
%feature("docstring", "Set the title of a bookmark.") SetBookmarkTitle;
bool SetBookmarkTitle(std::wstring id, std::wstring title);
%feature("docstring", "Set the URL of a bookmark.") SetBookmarkURL;
bool SetBookmarkURL(std::wstring id, const std::wstring url);
%feature("docstring", "Remove (delete) a bookmark.") RemoveBookmark;
bool RemoveBookmark(std::wstring id);
%feature("docstring", "Open the Find box in the given or first browser "
"window.") OpenFindInPage;
void OpenFindInPage(int window_index=0);
%feature("docstring", "Determine if the find box is visible in the "
"given or first browser window.") IsFindInPageVisible;
bool IsFindInPageVisible(int window_index=0);
// Tabs and windows methods
%feature("docstring", "Open a new browser window.") OpenNewBrowserWindow;
bool OpenNewBrowserWindow(bool show);
%feature("docstring", "Close a browser window.") CloseBrowserWindow;
bool CloseBrowserWindow(int window_index);
%feature("docstring", "Fetch the number of browser windows. Includes popups.")
int GetBrowserWindowCount();
%feature("docstring", "Get the index of the active tab in the given or "
"first window. Indexes are zero-based.") GetActiveTabIndex;
int GetActiveTabIndex(int window_index=0);
%feature("docstring", "Activate the tab at the given zero-based index in "
"the given or first window. Also brings the window to the front. "
"Returns True on success.") ActivateTab;
bool ActivateTab(int tab_index, int window_index=0);
%feature("docstring", "Get the title of the active tab for the given or "
"first window.") GetActiveTabTitle;
std::wstring GetActiveTabTitle(int window_index=0);
%feature("docstring", "Get the URL for the active tab. for the given or "
"first window. Returns an instance of GURL") GetActiveTabURL;
GURL GetActiveTabURL(int window_index=0);
%feature("docstring", "Count of the number of tabs in the given or "
"first window.") GetTabCount;
int GetTabCount(int window_index=0);
%feature("docstring", "Create a new tab at the end of given or first browser "
"window and activate it. Blocks until the page is loaded. "
"Returns True on success.") AppendTab;
bool AppendTab(const GURL& tab_url, int window_index=0);
%feature("docstring", "Set the value of the cookie at cookie_url to value "
"for the given window index and tab index. "
"Returns True on success.") SetCookie;
bool SetCookie(const GURL& cookie_url, const std::string& value,
int window_index=0, int tab_index=0);
%feature("docstring", "Get the value of the cookie at cookie_url for the "
"given window index and tab index. "
"Returns empty string on error or if there is no value for the "
"cookie.") GetCookie;
std::string GetCookie(const GURL& cookie_url, int window_index=0,
int tab_index=0);
// Misc methods
%feature("docstring", "Install an extension from the given path. The path "
"must be absolute and may be a crx file or an unpacked extension "
"directory. Returns the extension ID if successfully installed and "
"loaded. Otherwise, returns the empty string.") InstallExtension;
std::string InstallExtension(const std::string& extension_path, bool with_ui);
%feature("docstring", "Get a proxy to the browser window at the given "
"zero-based index.") GetBrowserWindow;
scoped_refptr<BrowserProxy> GetBrowserWindow(int window_index);
// Meta-method
%feature("docstring", "Send a sync JSON request to Chrome. "
"Returns a JSON dict as a response. "
"Given timeout in milliseconds."
"Internal method.")
std::string _SendJSONRequest(int window_index,
const std::string& request,
int timeout);
%feature("docstring", "Execute a string of javascript in the specified "
"(window, tab, frame) and return a string.") ExecuteJavascript;
std::wstring ExecuteJavascript(const std::wstring& script,
int window_index=0,
int tab_index=0,
const std::wstring& frame_xpath="");
%feature("docstring", "Evaluate a javascript expression in the specified "
"(window, tab, frame) and return the specified DOM value "
"as a string. This is a wrapper around "
"window.domAutomationController.send().") GetDOMValue;
std::wstring GetDOMValue(const std::wstring& expr,
int window_index=0,
int tab_index=0,
const std::wstring& frame_xpath="");
%feature("docstring", "Resets to the default theme. "
"Returns true on success.") ResetToDefaultTheme;
bool ResetToDefaultTheme();
namespace net {
// TestServer
"TestServer. Serves files in data dir over a local http server")
class TestServer {
enum Type {
TestServer(Type type, const FilePath& document_root);
%feature("docstring", "Start TestServer over an ephemeral port") Start;
bool Start();
%feature("docstring", "Stop TestServer") Stop;
bool Stop();
%feature("docstring", "Get FilePath to the document root") document_root;
const FilePath& document_root() const;
std::string GetScheme() const;
%feature("docstring", "Get URL for a file path") GetURL;
GURL GetURL(const std::string& path) const;