splinter - python acceptance testing for web applications

what’s new in splinter 0.0.3?

install

$ [sudo] pip install splinter

development

Pull requests are very welcome! Make sure your patches are well tested.

running the tests

if you are using a virtualenv, all you need is:

$ make test

community

irc channel

#cobrateam channel on irc.freenode.net

documentation

Browser

To use splinter you need create a Browser instance:

from splinter.browser import Browser
browser = Browser()

splinter support three drivers: chrome, firefox and zopetestbrowser

browser = Browser('webdriver.chrome')
browser = Browser('webdriver.firefox')
browser = Browser('zope.testbrowser')

Reload a page

You can reload a page using reload method:

browser.reload()

Browser.title

You can get the title of the visited page using the title attribute:

browser.title

Verifying page content with Browser.html

You can use the html attribute to get the html content of the visited page:

browser.html

Verifying page url with Browser.url

The visited page’s url can be accessed by the url attribute:

browser.url

Finding elements

For finding elements you can use five methods, one for each selector type css, xpath, tag, name, id:

browser.find_by_css('h1')
browser.find_by_xpath('//h1')
browser.find_by_tag('h1')
browser.find_by_name('name')
browser.find_by_id('firstheader')

These methods returns a list of all found elements.

you can get the first found element:

browser.find_by_name('name').first

You can use too the last attribute, that returns the last found element:

browser.find_by_name('name').last

Get element using index

You also use index for get a element

browser.find_by_name('name')[1]

all elements and find_by_id

A web page should be only one id per page. Then find_by_id() method return always a list with one element.

Element not found exception

If element not found, find methods returns a empty list. But, if you try, access a element in list raises the splinter.element_list.ElementDoesNotExist exception.

Get element value

In order to retrieve an element’s value, use the value property:

browser.find_by_css('h1').first.value

or

element = browser.find_by_css('h1').first
element.value

Clicking buttons

You can click in buttons. Splinter follows any redirects, and submits forms associated with buttons.

browser.find_by_name('send').first.click()

or

browser.find_link_by_text('my link').first.click()

Interacting with forms

browser.fill('query', 'my name')
browser.attach_file('file', '/path/to/file/somefile.jpg')
browser.choose('some-radio')
browser.check('some-check')
browser.uncheck('some-check')
browser.select('uf', 'rj')

Verifying if element is visible or invisible

To check if an element is visible or invisible, use the visible property. For instance:

browser.find_by_css('h1').first.visible

will be True if the element is visible, or False if it is invisible.

Ajax and async javascript

When working with ajax and async javascript, it’s common you work with with an element which is not yet present on the page.

splinter have methods for verifying if element is present in a page, that wait for a element and returns True if element is present:

browser.is_element_present_by_css('h1')
browser.is_element_present_by_xpath('//h1')
browser.is_element_present_by_tag('h1')
browser.is_element_present_by_name('name')
browser.is_element_present_by_id('firstheader')

You can verify too if element is not present in a page:

browser.is_element_not_present_by_css('h1')
browser.is_element_not_present_by_xpath('//h1')
browser.is_element_not_present_by_tag('h1')
browser.is_element_not_present_by_name('name')
browser.is_element_not_present_by_id('firstheader')

Executing javascript

You can easily execute JavaScript, in drivers which support it:

browser.execute_script("$('body').empty()")

You can return the result of the script:

browser.evaluate_script("4+4") == 8

Using iframes

You can use the get_iframe method and the with statement to interact with iframes.

with browser.get_iframe('iframemodal') as iframe:
    iframe.do_stuff()

Handling alerts and prompts

IMPORTANT: Only Firefox webdriver has support for alerts and prompts. Calling any of the following methods from other webdriver (like Chrome) will raise NotImplementedError.

You can deal with alerts and prompts using the get_alert method.

alert = browser.get_alert()
alert.text
alert.accept()
alert.dismiss()

In case of prompts, you can answer it using the fill_with method.

prompt = browser.get_alert()
prompt.text
prompt.fill_with('text)
prompt.accept()
prompt.dismiss()

You can use the with statement to interacte with both alerts and prompts too.

with browser.get_alert() as alert:
    alert.do_stuff()

If there’s not any prompt or alert, get_alert will return None. Remember to always use at least one of the alert/prompt ending methods (accept and dismiss). Otherwise your browser instance will be frozen until you accept or dismiss the alert/prompt correctly.