Welcome to django_seleniumhelpers’s documentation!¶
Contents¶
Getting started¶
Features¶
- Skip selenium tests
- Select test browser
- Helper functions to simplify common use cases.
Issues/contribute¶
Report any issues at the github project page, and feel free to add your own guides/experiences to the wiki, and to contribute changes using pull requests.
Setup¶
Add 'seleniumhelpers'
to INSTALLED_APPS
.
Usage¶
Subclass seleniumhelpers.SeleniumTestCase
instead of
django.test.LiveServerTestCase
in your testcases.
Example¶
from seleniumhelpers import SeleniumTestCase
class TestFrontpage(SeleniumTestCase):
def test_frontpageimage(self):
# Use our shortcut instead of self.selenium.get(self.live_server_url + '/something')
self.getPath('/something/')
# Fail unless the expected image and text is available within 10 secons
self.waitForCssSelector('img.frontpageimage')
self.waitForText(u'This is the frontpage image text.')
# Assert that we remembered to close the body. Mostly to show how
# to get hold of the selenium WebDriver object
# Note: The selenium attribute is actually set as an attribute on
# the class in SeleniumTestCase.setUpClass()
self.assertTrue('</body>' in self.selenium.page_source)
Running tests¶
You can run the tests just like normal Django tests, however we provide the ability to override the browser used for the tests, and to completely skip all selenium tests.
Select selenium browser:
$ SELENIUM_BROWSER=Firefox python manage.py test
See available browsers:
$ python manage.py listseleniumbrowsers
Skip selenium tests:
$ SKIP_SELENIUMTESTS=1 python manage.py test
Note
Settings can also be set in settings.py
. See settings.
Configure timout¶
You can configure the default timeout using SELENIUM_DEFAULT_TIMEOUT
, in
settings.py
or as environment variables, just like SKIP_SELENIUMTESTS
and SELENIUM_BROWSER
. Example:
$ SELENIUM_BROWSER=Firefox SELENIUM_DEFAULT_TIMEOUT=10 python manage.py test
The default timeout is 4
seconds, which should be enough unless you are
running on a very slow machine.
Use Selenium RC¶
Using Selenium RC is easy, it only requires you to run the RC-server, and use an additional setting:
Download selenium-server-standalone-XXXX.jar from http://code.google.com/p/selenium/downloads/list.
Run the RC-server:
$ java -jar selenium-server-standalone-XXXX.jar
Run the tests with SELENIUM_USE_RC:
$ SELENIUM_USE_RC=true SELENIUM_BROWSER=Opera python manage.py test
Use Chrome or Chromium¶
Download and install chromedriver (webdriver for Chrome/Chromium) with one of these methods:
- Install with
brew install chromedriver
on Mac OSX if you use Homebrew. - Download from http://chromedriver.storage.googleapis.com/index.html.
Run with SELENIUM_BROWSER=Chrome
.
PhantomJS¶
We support PhantomJS via ghostdriver.
Requirements¶
You need to build PhantomJS as described on the ghostdriver website.
Running tests with PhantomJS and ghostdriver¶
Run PhantomJS with ghostdriver on port 8080
as described on the ghostdriver website:
$ phantomjs /path/to/ghostdriver/src/main.js 8080
Run the tests with SELENIUM_BROWSER=phantomjs
:
SELENIUM_BROWSER=phantomjs python manage.py test
Settings¶
All the settings can be set in settings.py
, and most settings can be set
through using environment variables. If a setting is both in settings.py
and as an environment variable, the environment variable is used.
List of settings¶
- SKIP_SELENIUMTESTS
- Skip all seleniumtests.
- SELENIUM_BROWSER
- The selenium browser to use. Defaults to
Chrome
. - SELENIUM_USE_RC
- If
bool(SELENIUM_USE_RC)
isTrue
, we use the Selenium RC server instead of webdriver to run the tests.SELENIUM_BROWSER
is forwarded to the RC-server as the browser. - SELENIUM_DEFAULT_TIMEOUT
- The default timeout, in seconds, of the
waitFor*
methods. Defaults to4
.
API-docs¶
SeleniumTestCase API docs¶
-
class
seleniumhelpers.
SeleniumTestCase
(methodName='runTest')¶ Extends
django.test.LiveServerTestCase
to simplify selenium testing.-
executeScript
(script, element)¶ Shortcut for
self.selenium.executeScript(script, element)
.
-
failIfCssSelectorFound
(element, css_selector, msg='CSS selector, "{css_selector}" matches at least one element, when we expected it not to.')¶ Assert that
element.find_element_by_css_selector(css_selector)
does not raiseNoSuchElementException
.
-
classmethod
getDriver
(browser, use_rc)¶ Override this to create customize the
selenium
-attribute.Parameters: - browser – The value of the
SELENIUM_BROWSER
setting. - use_rc – The value of
bool(SELENIUM_USE_RC)
.
- browser – The value of the
-
getInnerHtml
(element)¶ Get
innerHTML
of the given element.
-
getPath
(path)¶ Shortcut for
self.selenium.get(...)
withpath
prefixed bylive_server_url
as argument.
-
classmethod
setUpClass
()¶ Adds the
selenium
attribute to the class. Theselenium
attribute defaults to an instance ofselenium.webdriver.Chrome
, however this can be overridden using theSELENIUM_BROWSER
django setting or environment variable. If both the django setting and and environment variable is set, the environment variable is used. This means that you can set the default value insettings.py
and override it in an environment variable, typically when running thetest
command:SELENIUM_BROWSER=Firefox python manage.py test
-
waitFor
(item, fn, timeout=4, msg=None)¶ Wait for the
fn
function to returnTrue
. Theitem
is forwarded as argument tofn
.Example (wait for text in an element):
waitFor(myelem, lambda myelem: len(myelem.text) > 0, msg='myelem is empty')
-
waitForAndFindElementByCssSelector
(cssselector, within=None, timeout=4)¶ Use
waitForCssSelector()
to wait untilcssselector
is found, then useself.selenium.find_element_by_css_selector
to locate and return the element.Parameters: - within – The element to run
find_element_by_css_selector()
on. Defaults toself.selenium
. - timeout – Fail unless the
cssselector
is found beforetimeout
seconds.
- within – The element to run
-
waitForCssSelector
(cssselector, timeout=4, within=None, msg='No elements match css selector "{cssselector}".')¶ Wait for the given
cssselector
.Parameters: - within – The element to run
find_element_by_css_selector()
on. Defaults toself.selenium
. - timeout – Fail unless the
cssselector
is found beforetimeout
seconds.
- within – The element to run
-
waitForCssSelectorNotFound
(cssselector, timeout=4, within=None, msg='CSS selector, "{cssselector}" matches at least one element, when we expected it not to.')¶ Wait for the given
cssselector
not to be found.Parameters: - within – The element to run
find_elements_by_css_selector()
on. Defaults toself.selenium
. - timeout – Fail if the
cssselector
is still found aftertimeout
seconds.
- within – The element to run
-
waitForDisabled
(element, timeout=4, msg='The element is not disabled.')¶ Wait for the given
element
to become disabled (element.is_enabled() == False
).Parameters: timeout – Fail unless the element
becomes disabled beforetimeout
seconds. Defaults to10
.
-
waitForDisplayed
(element, timeout=4, msg='The element is not displayed.')¶ Wait for the given element to be displayed.
-
waitForEnabled
(element, timeout=4, msg='The element is not enabled.')¶ Wait for the given
element
to become enabled (element.is_enabled() == True
).Parameters: timeout – Fail unless the element
becomes enabled beforetimeout
seconds.
-
waitForNotDisplayed
(element, timeout=4, msg='The element is not hidden.')¶ Wait for the given element to be hidden.
-
waitForText
(text, timeout=4, msg='Could not find text "{text}"', within=None)¶ Wait for
text
to appear inselenium.page_source
or from the text of an element.Parameters: - within – The element to find text within (uses within.text). If
this is not specified, we get text from
selenium.page_source
. - timeout – Fail unless the
text
appears inselenium.page_source
beforetimeout
seconds has passed.
- within – The element to find text within (uses within.text). If
this is not specified, we get text from
-
waitForTitle
(title, timeout=4)¶ Wait until the page title (title-tag) equals the given
title
.
-
waitForTitleContains
(title, timeout=4)¶ Wait until the page title (title-tag) contains the given
title
.
-
Helper-functions¶
-
seleniumhelpers.
get_setting_with_envfallback
(setting, default=None, typecast=None)¶ Get the given setting and fall back to the default of not found in
django.conf.settings
oros.environ
.Parameters: - settings – The setting as a string.
- default – The fallback if
setting
is not found. - typecast – A function that converts the given value from string to another type.
E.g.: Use
typecast=int
to convert the value to int before returning.
-
seleniumhelpers.
get_default_timeout
()¶ Get the default timeout. Uses
get_setting_with_envfallback()
to getSELENIUM_DEFAULT_TIMEOUT
. Defaults to4
.
Customize the driver-object (cls.selenium)¶
The selenium
-attribute of the seleniumhelpers.SeleniumTestCase`
is
created in the seleniumhelpers.SeleniumTestCase.getDriver()
classmethod.
You can override this method if you have more advanced needs than the simple
customizations provided by the default implementation.
Example¶
This example makes it possible to run Firefox3.6 if SELENIUM_BROWSER=="Firefox3.6"
:
from seleniumhelpers import SeleniumTestCase
from selenium import webdriver
class CustomSeleniumTestCase(SeleniumTestCase):
@classmethod
def getDriver(cls, browser, use_rc):
if browser == 'Firefox3.6':
return webdriver.Remote('desired_capabilities': {'browser_name': browser,
'version': '3.6'})
else:
return super(CustomSeleniumTestCase, self).getDriver(browser, use_rc)
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line