Elemental¶

A helpful wrapper for Selenium

Installation¶

pip install WebElemental

Hello World!¶

from WebElemental import Elemental

# Running headless FireFox is the default.
elemental = Elemental() # Defaults to xvfb=True, driver=FireFox
# If xvfb is not installed, it will be bypassed automatically.

# If you explicitly don't want headless operation:
elemental = Elemental(xvfb=False)

Once we’ve initialized Elemental, we still need to kick off the browser. I’ve made this a manual step so that it is easy to start and stop different browsers using the same Elemental instance if desired.

# Start your engines...

elemental.start()

# DO SOME STUFF
print(elemental.current_url())
# outputs 'http://someaddress.here/page.html'

elemental.click('#some-button') # Clicks a button.

elemental.js('console.log("I am executing JS on the page!");')

elem = elemental.find_element('#my-id') # Returns a selenium element object

elems = elemental.find_elements('.some-class') # Returns a list of selenium element objects

form_data = {
    '#username': 'person',
    '#password': 'somepass'
}
elemental.fill(form_data) # Fills a form. Takes a dict of CSS keys and values.

elemental.screenshot('/tmp/screenshot1.png')

elemental.stop()

As you can see, there is almost no reason to ever interact with the selenium browser object directly. This is by design. If you ever find yourself needing to, it means that you have uncovered a need that was unanticipated by the initial design of this utility.

If you are reading this, you are a programmer so it would be nice if you made the method you require and sent a PR. The more people use and develop this framework, the better it will become.

So even though I don’t recommend using it, you still have access to the selenium browser object.

elemental.browser.find_elements_by_id('#some-id') # Use elemental.find_element instead.

TestElemental¶

TestElemental inherits Elemental so it has all the same methods that Elemental has but it adds some additional methods that are useful for testing.

Documentation¶

Elemental¶

class WebElemental.Elemental(xvfb=True, driver='Firefox', mootools=False, timeout=90, width=1440, height=1200, firefox_version=46, desired_capabilities='FIREFOX', command_executor='http://127.0.0.1:4444/wd/hub')[source]¶

Elemental runs an instance of Selenium and adds a lot of helpful browser methods.

Generally this class aims to make the experience of using Selenium better overall.

Many functions take a “selector” argument. These can be any valid CSS selector.. See https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_started/Selectors

alert_present()[source]¶: Checks to see if an alert is present.

back()[source]¶: Goes one step back in the browser’s history. Just a convenient wrapper around the browser’s back command

clear(selector)[source]¶

Clears value of an element by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

click(selector, elem=None)[source]¶

Clicks an element.

selector: str: A CSS selector to search for. This can be any valid CSS selector..

click_all(selector)[source]¶

Clicks all elements.

selector: str: A CSS selector to search for. This can be any valid CSS selector.. All matching elements will be clicked.

close_alert(ignore_exception=False)[source]¶

Closes any alert that is present. Raises an exception if no alert is found.

ignore_exception: bool: Does not throw an exception if an alert is not present.

close_all_other_windows()[source]¶: Closes all windows except for the currently active one.

close_window(window_name=None, title=None, url=None)[source]¶

Close window by name, title, or url.

window_name: str: The name of the window to switch to.
title: str: The title of the window you wish to switch to.
url: str: URL of the window you want to switch to.

current_url()[source]¶

Gets current URL of the browser object.

str: The curent URL.

fill(form_dict)[source]¶

Fills a form using Selenium. This helper will save a lot of time and effort because working with form data can be tricky and gross.

form_dict: dict: Takes in a dict where the keys are CSS selectors and the values are what will be applied to them.

fill_form(form_list)[source]¶

This helper can be used directly but it is much easier to use the “fill” method instead.

form_list: list of dict: A list of dictionaries where the key is the search method and the value is what is passed to Selenium
clear: bool: True/False value indicating whether or not to clear out the input currently in any text inputs.

find_element(selector)[source]¶

Finds an element by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

selenium.webdriver.remote.webelement.WebElement or None: Returns an element or nothing at all

find_elements(selector)[source]¶

Finds elements by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

list of selenium.webdriver.remote.webelement.WebElement or list: Returns a list of elements or empty list

forward()[source]¶: Goes one step forward in the browser’s history. Just a convenient wrapper around the browser’s forward command

get_alert()[source]¶: Returns instance of Alert.

get_element(selector)[source]¶

Gets element by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

selenium.webdriver.remote.webelement.WebElement: A selenium element object.

get_elements(selector)[source]¶

Gets elements by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

list of selenium.webdriver.remote.webelement.WebElement: A list of selenium element objects.

get_page_source()[source]¶: Gets the source code of the page.

get_text(selector)[source]¶

Gets text from inside of an element by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

str: The text from inside of a selenium element object.

get_texts(selector)[source]¶

Gets all the text from all elements found by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

list of str: A list of text strings from inside of all found selenium element objects.

get_value(selector)[source]¶

Gets value of an element by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

str: The value of a selenium element object.

go(address)[source]¶

Go to a web address. (self.browser should be available, but not needed.)

address: str: The address (URL)

hover(selector, click=False)[source]¶

Hover over the element matched by selector and optionally click it.

selector: str: Any valid CSS selector
click: bool: Whether or not to click the element after hovering defaults to False

is_text_on_page(text)[source]¶

Finds text if it is present on the page.

text: str: The text to search for.

js(js_str, *args)[source]¶

Run some JavaScript and return the result.

js_str: str: A string containing some valid JavaScript to be ran on the page.

str or bool or list or dict: Returns the result of the JS evaluation.

refresh_page(refresh_method='url')[source]¶

Refreshes the current page

method: str: The method used to refresh the page. Defaults to “url” which navigates to the current_url

save_page_source(path='/tmp/selenium-page-source.html')[source]¶

Saves the raw page html in it’s current state. Takes a path as a parameter.

path: str: Defaults to: /tmp/selenium-page-source.html

screenshot(path=None)[source]¶

Saves a screenshot. Takes a path as a parameter.

path: str: Defaults to: /tmp/selenium-screenshot.png

scroll_browser(amount, direction='down')[source]¶

Scrolls the browser by the given amount in the specified direction.

amount: int: number of pixels to scroll
direction: str: (up, down, left, right) defaults to ‘down’

scroll_to_element(selector, elem=None)[source]¶

Scrolls the given element into view.

selector: str: Any valid css selector

send_key(selector, key, wait_for='presence', **kwargs)[source]¶

Sets value of an element by CSS selector.

selector: str

A CSS selector to search for. This can be any valid CSS selector.

key: str

A str representation of a special key to send.

Some available keys and their string representations:

ADD = u'\ue025'
ALT = u'\ue00a'
ARROW_DOWN = u'\ue015'
ARROW_LEFT = u'\ue012'
ARROW_RIGHT = u'\ue014'
ARROW_UP = u'\ue013'
BACKSPACE = u'\ue003'
BACK_SPACE = u'\ue003'
CANCEL = u'\ue001'
CLEAR = u'\ue005'
COMMAND = u'\ue03d'
CONTROL = u'\ue009'
DECIMAL = u'\ue028'
DELETE = u'\ue017'
DIVIDE = u'\ue029'
DOWN = u'\ue015'
END = u'\ue010'
ENTER = u'\ue007'
EQUALS = u'\ue019'
ESCAPE = u'\ue00c'
F1 = u'\ue031'
F10 = u'\ue03a'
F11 = u'\ue03b'
F12 = u'\ue03c'
F2 = u'\ue032'
F3 = u'\ue033'
F4 = u'\ue034'
F5 = u'\ue035'
F6 = u'\ue036'
F7 = u'\ue037'
F8 = u'\ue038'
F9 = u'\ue039'
HELP = u'\ue002'
HOME = u'\ue011'
INSERT = u'\ue016'
LEFT = u'\ue012'
LEFT_ALT = u'\ue00a'
LEFT_CONTROL = u'\ue009'
LEFT_SHIFT = u'\ue008'
META = u'\ue03d'
MULTIPLY = u'\ue024'
NULL = u'\ue000'
NUMPAD0 = u'\ue01a'
NUMPAD1 = u'\ue01b'
NUMPAD2 = u'\ue01c'
NUMPAD3 = u'\ue01d'
NUMPAD4 = u'\ue01e'
NUMPAD5 = u'\ue01f'
NUMPAD6 = u'\ue020'
NUMPAD7 = u'\ue021'
NUMPAD8 = u'\ue022'
NUMPAD9 = u'\ue023'
PAGE_DOWN = u'\ue00f'
PAGE_UP = u'\ue00e'
PAUSE = u'\ue00b'
RETURN = u'\ue006'
RIGHT = u'\ue014'
SEMICOLON = u'\ue018'
SEPARATOR = u'\ue026'
SHIFT = u'\ue008'
SPACE = u'\ue00d'
SUBTRACT = u'\ue027'
TAB = u'\ue004'
UP = u'\ue013'

kwargs:

passed on to wait_for_*

set_select_by_text(select, text)[source]¶

Set the selected value of a select element by the visible text.

select: str or selenium.webdriver.remote.webelement.WebElement: Any valid CSS selector or a selenium element
text: str: The visible text in the select element option. (Not the value)

set_select_by_value(select, value)[source]¶

Set the selected value of a select element by the value.

select: str or selenium.webdriver.remote.webelement.WebElement: Any valid CSS selector or a selenium element
value: str: The value on the select element option. (Not the visible text)

set_selectize(selector, value, text=None, clear=True, blur=False)[source]¶

Sets visible value of a selectize control based on the “selectized” element.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
value: str: The value of the option to select. (Stored Value)
text: str: The visible value that the user sees. (Visible value, if different than the stored value)
clear: bool: Whether or not we should clear the selectize value first. Defaults to True
blur: bool: Whether or not we should blur the element after setting the value. This corresponds to the ‘selectOnTab’ selecize setting. Defaults to False

set_value(selector, value, clear=True, blur=True, **kwargs)[source]¶

Sets value of an element by CSS selector.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
value: str: The value to set on the element matched by the selector.
clear: bool: Whether or not we should clear the element’s value first. If false, value will be appended to the current value of the element.
blur: bool: Whether or not we should blur the element after setting the value. Defaults to True
kwargs:: passed on to wait_for_visible

set_values(values, clear=True, blur=True, **kwargs)[source]¶

Sets values of elements by CSS selectors.

values: list of list or dict or list of dict: A list of lists where index 0 is a selector string and 1 is a value.
clear: bool: Whether or not we should clear the element’s value first. If false, value will be appended to the current value of the element.
blur: bool: Whether or not we should blur the element after setting the value. Defaults to True
kwargs:: passed on to wait_for_visible

start()[source]¶

Starts Selenium and (optionally) starts XVFB first.

Note:

XVFB is typically used with headless runs. If you do not use XVFB and the browser you have selected has a GUI (Firefox, Chrome...) then your browser will launch and you will be able to view the test as it is being ran.

This is particularly useful for problematic test runs or when building new tests.

stop()[source]¶

Stops Selenium. Also stops XVFB if it was launched as a part of this class run.

Note:

Anything you don’t stop here will need to be cleaned up with a kill command if you launched it outside of nosetests.

switch_to_window(window_name=None, title=None, url=None)[source]¶

Switch to window by name, title, or url.

window_name: str: The name of the window to switch to.
title: str: The title of the window you wish to switch to.
url: str: URL of the window you want to switch to.

wait_for(method, **kwargs)[source]¶

Wait for the supplied method to return True. A simple wrapper for _wait_for().

method: callable: The function that determines the conditions for the wait to finish
timeout: int: Number of seconds to wait for method to return True

wait_for_alert(**kwargs)[source]¶: Shortcut for waiting for alert. If it not ends with exception, it returns that alert.

wait_for_all_invisible(selector='', **kwargs)[source]¶

Wait for all elements that match selector to be invisible.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
kwargs:: Passed on to _wait_for

wait_for_clickable(selector='', **kwargs)[source]¶

Wait for an element to be clickable.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
kwargs:: Passed on to _wait_for

wait_for_invisible(selector='', **kwargs)[source]¶

Wait for an element to be invisible.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
kwargs:: Passed on to _wait_for

wait_for_js(js_script, **kwargs)[source]¶

Wait for the given JS to return true.

js_script: str: valid JS that will run in the page dom
kwargs:: passed on to _wait_for

wait_for_ko(selector='', **kwargs)[source]¶

Wait for an element to be bound by Knockout JS.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
kwargs:: Passed on to _wait_for

wait_for_opacity(selector, opacity, **kwargs)[source]¶

Wait for an element to reach a specific opacity.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
opacity: float: The opacity to wait for.
kwargs:: Passed on to _wait_for

wait_for_presence(selector='', **kwargs)[source]¶

Wait for an element to be present. (Does not need to be visible.)

selector: str: A CSS selector to search for. This can be any valid CSS selector.
kwargs:: Passed on to _wait_for

wait_for_selected(selector='', selected=True, **kwargs)[source]¶

Wait for an element (checkbox/radio) to be selected.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
selected: bool: Whether or not the element should be selected. Default True
kwargs:: Passed on to _wait_for

wait_for_text(selector='', text='', **kwargs)[source]¶

Wait for an element to contain a specific string.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
text: str: The string to look for. This must be precise. (Case, punctuation, UTF characters... etc.)
kwargs:: Passed on to _wait_for

wait_for_text_in_value(selector='', text='', **kwargs)[source]¶

Wait for an element’s value to contain a specific string.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
text: str: The string to look for. This must be precise. (Case, punctuation, UTF characters... etc.)
kwargs:: Passed on to _wait_for

wait_for_title(title, **kwargs)[source]¶

Wait for the page title to match given title.

title: str: The page title to wait for
kwargs:: Passed on to _wait_for

wait_for_url(url='', **kwargs)[source]¶

Wait for the current url to match the given url.

url: str: A regular expression to match against the current url
kwargs:: Passed on to _wait_for

wait_for_value(selector='', value='', **kwargs)[source]¶

Wait for an element to contain a specific string.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
value: str: The string to look for. This must be precise. (Case, punctuation, UTF characters... etc.)
kwargs:: Passed on to _wait_for

wait_for_visible(selector='', **kwargs)[source]¶

Wait for an element to be visible.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
kwargs:: Passed on to _wait_for

TestElemental¶

class WebElemental.TestElemental(base_url='http://127.0.0.1:5000', xvfb=True, driver='Firefox', mootools=False, timeout=90, width=1440, height=1200, root_path='./', firefox_version=46, desired_capabilities='FIREFOX', command_executor='http://127.0.0.1:4444/wd/hub')[source]¶

A class that extends Elemental and TestCase This class adds some additional testing capabilities and shortcuts to Elemental.

assert_alert_not_present()[source]¶: Asserts that an alert does not exist.

assert_alert_present()[source]¶: Asserts that an alert exists.

assert_element_contains_text(selector, text, wait_for='presence', **kwargs)[source]¶

Asserts that the text can be found inside of the element obtained from a given CSS selector.

text: str: The string to look for. Must be exact.
selector: str: A CSS selector to search for. This can be any valid CSS selector.
wait_for: str: ‘presence’ or ‘visible’ - defaults to presence
kwargs:: passed on to wait_for_*

assert_element_has_class(selector, cls, wait_for='presence', **kwargs)[source]¶

Asserts the element obtained from a given CSS selector has specified class. Parameters ———- selector: str

Any valid css selector

class: str: The class to check for
wait_for: str: ‘presence’ or ‘visible’ - defaults to presence
kwargs:: passed on to wait_for_*

assert_element_not_has_class(selector, cls, wait_for='presence', **kwargs)[source]¶

Asserts the element obtained from a given CSS selector does not have the specified class. Parameters ———- selector: str

Any valid css selector

class: str: The class to check for
wait_for: str: ‘presence’ or ‘visible’ - defaults to presence
kwargs:: passed on to wait_for_*

assert_exists(selector)[source]¶

Asserts that the element found from a given CSS selector exists on the page.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

assert_found(selector)[source]¶

Asserts that the element can be found.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

assert_not_found(selector)[source]¶

Asserts that the element cannot be found.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

assert_not_visible(selector)[source]¶

Asserts that the element found from a given CSS selector is NOT visible on the page.

selector: str: A CSS selector to search for. This can be any valid CSS selector.

assert_text_in_element(selector, text, wait_for='presence', **kwargs)[source]¶

Asserts that the text can be found inside of the element obtained from a given CSS selector.

text: str: The string to look for. Must be exact.
selector: str: A CSS selector to search for. This can be any valid CSS selector.
wait_for: str: ‘presence’ or ‘visible’ - defaults to presence
kwargs:: passed on to wait_for_*

assert_text_in_elements(selector, text, wait_for='presence', **kwargs)[source]¶

Asserts that the text can be found inside of the elements obtained from a given CSS selector.

text: str: The string to look for. Must be exact.
selector: str: A CSS selector to search for. This can be any valid CSS selector.
wait_for: str: ‘presence’ or ‘visible’ - defaults to presence
kwargs:: passed on to wait_for_*

assert_text_in_page(text)[source]¶

Asserts that the text exists on the page.

text: str: Text to search for.

assert_text_not_in_page(text)[source]¶

Asserts that the text does not exist on the page.

text: str: Text to search for.

assert_url(url)[source]¶

Asserts that the current URL is equal to a specific value.

url: str: The URL to assert.

assert_value_of_element(selector, value, wait_for='presence', **kwargs)[source]¶

Asserts the value of the element obtained from a given CSS selector.

value: str: The string to look for. Must be exact.
selector: str: A CSS selector to search for. This can be any valid CSS selector.
wait_for: str: ‘presence’ or ‘visible’ - defaults to presence
kwargs:: passed on to wait_for_*

assert_visible(selector, **kwargs)[source]¶

Asserts that the element found from a given CSS selector is visible on the page.

selector: str: A CSS selector to search for. This can be any valid CSS selector.
kwargs:: passed on to wait_for_presence

goto(url, wait_for_visible=None, wait_for_presence=None)[source]¶

Shortcut to go to a relative path of the base_url. Useful for navigation in the same website.

url: str: Relative url to go to.
wait_for_visible: str: CSS selector to wait for visibility of after navigation.
wait_for_presence: str: CSS Selector to wait for presence of after navigation.

wait(seconds=500)[source]¶

Sleeps for some amount of time.

seconds: int: Seconds to sleep for.