http://github.com/actmd/elementium

jQuery-style syntactic sugar for highly reliable automated browser testing in Python

• Chainable methods with obvious names
• Easy to read
• Concise to write
• Built-in fault tolerance

For an introduction to why you'd want to use Elementium, take a look at the following post.

# From http://selenium-python.readthedocs.org/en/latest/getting-started.html

from selenium import webdriver
from selenium.webdriver.common.keys import Keys

driver = webdriver.Firefox()
driver.get("http://www.python.org")
assert "Python" in driver.title
elem = driver.find_element_by_name("q")
elem.send_keys("selenium")
elem.send_keys(Keys.RETURN)
driver.close()

from selenium import webdriver
from selenium.webdriver.common.keys import Keys
from elementium.drivers.se import SeElements

se = SeElements(webdriver.Firefox())
se.navigate("http://www.python.org").insist(lambda e: "Python" in e.title)
se.find("q").write("selenium" + Keys.RETURN)

pip install elementium

git clone git@github.com:actmd/elementium.git
cd elementium
python setup.py install

Elementium has been tested for Python 2.6, 3.2, 3.3, 3.4, and pypy using Travis CI

Elementium includes by default a wrapper for the Selenium Python Bindings. As such, all of the usage examples make use of the Selenium driver.

from selenium import webdriver
from elementium.drivers.se import SeElements

se = SeElements(webdriver.Firefox())

se.navigate("http://www.google.com")

Elementium simplifies most of Selenium's many find methods...

• find_element_by_id
• find_element_by_name
• find_element_by_tag_name
• find_element_by_class_name
• find_element_by_css_selector
• find_element_by_link_text
• find_element_by_partial_link_text

...into two find() and find_link() methods:

# Find by ID
se.find("#foo")

# Find by name
se.find("[name='foo']")

# Find by tag name
se.find("input")

# Find by class name
se.find(".cssClass")

# Find by link text
se.find_link("Click me")

# Find by partial link text
se.find_link("Click", exact=False)

find() and find_link() will also return multiple elements, if present, so you can forget about all the additional find_elements_... methods, too:

<div>...</div> <div>...</div> <div>...</div>

len(se.find("div")) # == 3

Under the hood, find() returns a new SeElements object containing a list of all of the items that matched. (These individual items are also of type SeElements.)

The get method lets you pull out a specific item in a chainable manner.

<button>Foo</button> <button>Bar</button> <button>Baz</button>

# Get the second button
se.find("button").get(1)

If you would rather get the raw object (e.g. SeleniumWebElement) that is returned by the underlying driver, use items:

# Find elements on a page for a given class
buttons = se.find("button")
for button in buttons.items:
    print type(button)

The item alias will return the first raw item:

se.find("button").item

<input value="blerg" />

se.find("input").value() # returns 'blerg'

<button>Click me</button>

se.find("button").click()

<input type="checkbox" value="check1">
<input type="checkbox" value="check2">
<input type="checkbox" value="check3">

# Click all three checkboxes
se.find("input[type='checkbox']").click()

<input type="text" />

se.find("input").write("If not now, when?")

<select>
    <option value="cb">Corned Beef</option>
    <option value="ps">Pastrami</option>
</select>

# Select by visible text
se.find("select").select(text="Corned Beef")

# Select by value
se.find("select").select(value="cb")

# Select by index
se.find("select").select(i=0)

If manipulating a multiple select, you may use the deselect() method in a similar manner:

<select multiple>
    <option value="h">Hummus</option>
    <option value="t">Tahina</option>
    <option value="c">Chips</option>
    <option value="a">Amba</option>
</select>

# Deselect by visible text
se.find("select").deselect(text="Chips")

# Deelect by value
se.find("select").deselect(value="c")

# Deselect by index
se.find("select").deselect(i=2)

# Deselect all
se.find("select").deselect()

So far, we haven't taken any huge leaps from off-the-shelf Selenium, though we're certainly typing less!

One of the big issues with Selenium is waiting for pages to load completely and all of the retry logic that may have to be used to have tests that work well. A common solution is to wrap your code with "retry" functions.

For example, a naive way of retrying might have been:

browser = webdriver.Firefox()
els = None
while not els:
    els = browser.find_element_by_tag_name('button')
    time.sleep(0.5)

With Elementium, just tell find() to wait:

# Retry until we find a button on the page (up to 20 seconds by default)
se.find('button', wait=True)

Have a more complex success condition? Use until():

# Retry until we find 3 buttons on the page (up to 20 seconds by default)
se.find('button').until(lambda e: len(e) == 3)

# Retry for 60 seconds
se.find('button').until(lambda e: len(e) == 3, ttl=60)

Both of the above methods will raise a elementium.elements.TimeoutError if the element is not found in the specified period of time.

Basically all methods that are part of the SeElements object will be automatically retried for you. Under the hood, each selector (e.g. '.foo' or '#foo') is stored as a callback function (similar to something like lambda: selenium.find_element_by_id('foo')). This way, when any of the calls to any of the methods of an element has an expected error (StaleElementException, etc.) it will recall this function. If you perform chaining, this will actually propagate that refresh (called update()) up the entire chain to ensure that all parts of the call are valid. Cool!

(Look at the code for more detail.)

se.find('input').insist(lambda e: e.value() == 'Pilkington')

This works exactly like until() above, only it raises an AssertionError instead.

See the full Elementium documentation for more details on the following methods.

• filter()
• scroll()
• scroll_top()
• scroll_bottom()

The following are simply more reliable versions of their Selenium counterparts. Some have been renamed for ease of use.

• is_displayed()
• is_enabled()
• is_selected()
• text()
• tag_name()
• attribute()
• clear()
• parent()
• xpath()
• source()
• refresh()
• current_url()
• execute_script()
• get_window_size()
• set_window_size()
• switch_to_active_element()

There are a couple examples in the aptly named examples directory. Take a look there for fully functioning source code.

There are several features planned for the future to improve Elementium and they will be rolled out as they pass through our internal scrutiny. If you have great ideas, you can be part of Elementium's future as well!

If you would like to contribute to this project, you will need to use git flow. This way, any and all changes happen on the development branch and not on the master branch. As such, after you have git-flow-ified your elementium git repo, create a pull request for your branch, and we'll take it from there.

Elementium has been a collaborative effort of ACT.md.