$ [sudo] pip install splinter
Pull requests are very welcome! Make sure your patches are well tested.
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')
You can use the html attribute to get the html content of the visited page:
browser.html
The visited page’s url can be accessed by the url attribute:
browser.url
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
A web page should be only one id per page. Then find_by_id() method return always a list with one element.
For finding link elements you can use find_link_by_text or find_link_by_href:
browser.find_link_by_text('Link for Example.com')
or
browser.find_link_by_href('http://example.com')
These methods returns a list of all found elements.
For finding links by id, tag, name or xpath you should use other find methods (find_by_css, find_by_xpath, find_by_tag, find_by_name and find_by_id).
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.
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
You can click in links. To click in links by href or text you can use this. IMPORTANT: This methods return the first element always.
browser.click_link_by_href('/my_link')
or
browser.click_link_by_text('my link')
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()
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')
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.
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')
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
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()
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.