slickwd API Documentation¶

class slickwd.Browser(browser_type, remote_url=None, default_timeout=30)[source]¶

The Browser is the primary interface you have to automate a browser. An instance of Browser has the same methods no matter which browser it is you launch. It also abstracts away the creation of remote browser instances when using Selenium Grid or Selenium Server.

Most actions that the Browser has takes an argument called locator, which should be an instance of WebElementLocator. These are normally arranged into Page classes to make them reusable by multiple tests / functions. See Page Classes.

To create an instance of Browser, provide the browser type you would like, and the remote_url (if any):

from slickwd import Browser, BrowserType

browser = Browser(BrowserType.PHANTOMJS)
browser.go_to("http://www.google.com")

For more examples, see Examples.

click(locator, timeout=None, log=True)[source]¶

Click on an element using the mouse.

Parameters:	locator (`WebElementLocator`) – the locator that specifies which element to click on (usually defined on a Page class) timeout (int or float (float for sub-second precision)) – The amount of time (in seconds) to look before throwing a not found exception log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	The reference to this Browser instance.
Return type:	`Browser`

click_and_type(locator, keys, timeout=None, log=True)[source]¶

Click on an element using the mouse, then send keys to it. Mostly used for input elements of type text.

Parameters:	locator (`WebElementLocator`) – the locator that specifies which element to click on and type in (usually defined on a Page class) timeout (int or float (float for sub-second precision)) – The amount of time (in seconds) to look before throwing a not found exception log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	The reference to this Browser instance.
Return type:	`Browser`

exists(locator, timeout=None, log=True)[source]¶

Check to see if an element exists on a page. You can control how long to wait, and if the method should do any logging. If you specify 0 for the timeout, the framework will only look for the element once.

Parameters:	locator (`WebElementLocator`) – the locator to look for (usually defined on a Page class) timeout (int or float) – The amount of time (in seconds) to look before returning False log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	True if an element was found in the time specified
Return type:	bool

first_page_found(page_classes, timeout=None, log=True)[source]¶

Look for the first page class that returns true, and return it. This is useful when you are trying to detect if a particular flow is happening. Rather than waiting for one page class, this goes through a list each time and as soon as one returns true, it returns that element.

Parameters:	page_classes – The list of page classes or page class instances. Whatever you pass in here is what will be returned if found. timeout (int or float (float for sub-second precision)) – The amount of time (in seconds) to look before throwing a not found exception log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	A page class from the list passed in (if found), None otherwise

get_attribute_value(locator, attribute_name, timeout=None, log=True)[source]¶

Get the value of an html element’s attribute.

Parameters:	locator (`WebElementLocator`) – the locator that specifies which element to get the attribute value of attribute_name (str) – the name of the attribute to get timeout (int or float (float for sub-second precision)) – The amount of time (in seconds) to look before throwing a not found exception log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	the text of the element on success, exception raised on inability to find the element
Return type:	str

get_page_text()[source]¶

Get the text from the current web page. This tries to get the value of the “text” attribute of the html root element on the page.

Returns:	the text of the current page
Return type:	str

get_text(locator, timeout=None, log=True)[source]¶

Get the text of an element on the page.

Parameters:	locator (`WebElementLocator`) – the locator that specifies which element to get the text of timeout (int or float (float for sub-second precision)) – The amount of time (in seconds) to look before throwing a not found exception log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	the text of the element on success, exception raised on inability to find the element
Return type:	str

get_title(log=True)[source]¶

Get the current title of the page.

Parameters:	log (bool) – Whether or not to log
Returns:	the title of the page
Return type:	str

get_url(log=True)[source]¶

Get the current url of the web page.

Parameters:	log (bool) – Whether or not to log
Returns:	The URL as a string (how else would you represent it?)
Return type:	str

go_to(url, log=True)[source]¶: Navigate the browser to the url provided

quit(log=True)[source]¶

Close the browser and quit the current session

Returns:	this instance for chaining of methods
Return type:	`Browser`

refresh(log=True)[source]¶: Refresh the page. :return: The reference to this Browser instance. :rtype: Browser

screenshot_as_byte()[source]¶: Take a screenshot of the browser, and return it as a png byte array. :rtype: byte[]

select_option_by_text(locator, option_text, timeout=None, log=True)[source]¶

Select an option of a select element by partial or complete text.

Parameters:	locator (`WebElementLocator`) – the locator that specifies how to find the select element option_text (str) – The text of the option to select timeout (int or float (float for sub-second precision)) – The amount of time (in seconds) to look before throwing a not found exception log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	The reference to this Browser instance.
Return type:	`Browser`

type(locator, keys, timeout=None, log=True)[source]¶

Send key strokes to an element. Mostly used for input elements of type text.

Parameters:	locator (`WebElementLocator`) – the locator that specifies which element to send keystrokes to (usually defined on a Page class) timeout (int or float (float for sub-second precision)) – The amount of time (in seconds) to look before throwing a not found exception log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	The reference to this Browser instance.
Return type:	`Browser`

wait_for_page(page, timeout=None, log=True)[source]¶

Wait for a page class (container) to be present. This will cause that the page’s is_current_page method to be called until it returns true or a timeout is reached.

Parameters:	page (`Container`) – The page class (container) to wait for it’s is_current_page to return True timeout (int or float (use float for sub-second precision)) – the max time (in seconds) to wait before giving up on the page existing log (bool) – Should the activities of this method be logged, default is True
Returns:	this instance for chaining of methods
Return type:	`Browser`

class slickwd.BrowserType[source]¶

This enum is to help identify browsers to launch. The values are the desired capabilities. All values are static properties on the BrowserType class.

Example Use:

from slickwd import Browser, BrowserType

browser = Browser(BrowserType.CHROME)

CHROME = None¶: Chrome Browser (you must download chromedriver separately and place in path)

FIREFOX = None¶: Firefox Browser

HTMLUNITWITHJS = None¶: HTMLUnit with Javascript enabled, only for use with Remote

IE = None¶: Internet Explorer Browser (you must download internet explorer driver separately and place it in your path)

OPERA = None¶: Opera Browser

PHANTOMJS = None¶: PhantomJS headless browser (must download separately, phantomjs homepage)

SAFARI = None¶: Safari Browser

class slickwd.Container[source]¶

A generic container for structuring multiple WebElementLocator into groupings that help programmers find the right shared definition.

get_name()[source]¶

Get the full name of this page. If using nested Page Classes this will get the full dotted name of the page class.

Returns:	A string containing the best guess at the page class name.

is_current_page(browser)[source]¶

You should override this method in a subclass of Container. This method is used to see if what is in the browser currently matches one or more elements of this class. This method should be quick (timeout 0 for all your calls). It may get called a lot, so you may want to turn off logging for any browser methods called (log=False parameter).

Parameters:	browser – A `Browser` instance to use in detecting if this is the current page.
Returns:	True if the current page matches what is in the browser, False otherwise.

class slickwd.Find(by, value)[source]¶

Use the class methods on this class to create instances, which are used by the WebElementLocator class to find elements in a browser.

Example Usage:

Search_Query_Text_Field = WebElementLocator("Search Box", Find.by_name("q"))

This would create an instance of WebElementLocator called Search_Query_Text_Field that can be found on the page by looking for an element with the name property set to q.

Or(finder)[source]¶

You can _or_ multiple finders together by using the Or method. An example would be:

Search_Query_Text_Field = WebElementLocator("Search Box", Find.by_name("q").Or(Find.by_id("q")))

If you use this to include multiple finders, note that it is not super precise. The framework iterates over the list of finders, and the first one that returns an element wins.

Parameters:	finder (`Find`) – Another finder to consider when looking for the element.
Returns:	This same instance of Find with the other finder included.
Return type:	`Find`

classmethod by_class_name(class_name_value)[source]¶

Find a web element by looking for one that uses a particular css class name.

Parameters:	class_name_value (str) – the name of one of the css classes of the web element you are looking for
Returns:	an instance of Find that uses it’s css classes as the way to find the element.
Return type:	`Find`

classmethod by_css_selector(css_selector_value)[source]¶

Find a web element by using a css selector

Parameters:	css_selector_value (str) – the css selector that will identify the element
Returns:	an instance of Find that uses a css selector to find the element
Return type:	`Find`

classmethod by_id(id_value)[source]¶

Find a web element using the element’s _id_ attribute.

Parameters:	id_value (str) – the id of the web element you are looking for
Returns:	an instance of Find that uses the id as the way to find the element.
Return type:	`Find`

classmethod by_link_text(link_text_value)[source]¶

Find a web element (a link or <a> tag) using the element’s exact link text.

Parameters:	link_text_value (str) – the value of the link’s inner text
Returns:	an instance of Find that uses the link’s text as the way to find the element.
Return type:	`Find`

classmethod by_name(name_value)[source]¶

Find a web element using the element’s _name_ attribute.

Parameters:	name_value (str) – the value of the name attribute of the web element you are looking for
Returns:	an instance of Find that uses the name attribute as the way to find the element.
Return type:	`Find`

classmethod by_partial_link_text(partial_link_text_value)[source]¶

Find a web element (a link or <a> tag) using part of the element’s link text.

Parameters:	partial_link_text_value (str) – a subset of the value of the link’s inner text
Returns:	an instance of Find that uses part of the link’s text as the way to find the element.
Return type:	`Find`

classmethod by_tag_name(tag_name_value)[source]¶

Find an element using it’s tag name. This is more useful when trying to find multiple elements.

Parameters:	tag_name_value (str) – the name of the html tag for the element or elements your are looking for
Returns:	an instance of Find that looks for all elements on a page with a particular tag name
Return type:	`Find`

classmethod by_xpath(xpath_value)[source]¶

Find a web element by using a xpath.

Parameters:	xpath_value (str) – the xpath expression that will identify the element
Returns:	an instance of Find that uses an xpath expression to find the element
Return type:	`Find`

describe()[source]¶: Describe this finder in a plain english sort of way. This allows for better logging. Example output would be “name q” for Find.by_name(“q”).

class slickwd.WebElementLocator(name, finder)[source]¶

A WebElementLocator represents information about an element you are trying to find. It has a name field for nice logging, and a finder field (should be of type Find).

See Locators

describe()[source]¶

Describe the current locator in plain english. Used for logging.

Returns:	description of element locator including name and how it is looking for it
Return type:	str

find_all_elements_matching(wd_browser, log=True, angular=False)[source]¶

Find a list of elements that match a finder. This method can be useful if you are Using the Webdriver APIs and need to select from and inspect a list of elements.

There is no timeout because it will return an empty list if no matching elements are found.

Parameters:	wd_browser – The raw selenium webdriver driver instance. log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	list of matching elements
Return type:	list of web element

find_element_matching(wd_browser, timeout, log=True, angular=False)[source]¶

Find a single element matching the finder(s) that make up this locator before a timeout is reached. This method is used internally by the framework when you call any action on a WebElementLocator, however like is mentioned in Using the Webdriver APIs you can use this method to help you get the raw webelements from webdriver for your own use.

Parameters:	wd_browser – The selenium driver (webdriver) instance to use. timeout (int or float (use float for sub-second precision)) – the max time (in seconds) to wait before giving up on finding the element log (bool) – Whether or not to log details of the look for the element (default is True)
Returns:	a raw webdriver webelement type on success, None on failure