.. selenose documentation master file, created by
sphinx-quickstart on Sat Oct 29 16:20:54 2011.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Selenose
========
Selenose provides a set of `Selenium `_ related plugins/tasks for `nose `_/`django-jenkins `_ developed by `ShiningPanda `_.
The use of these plugins/tasks is detailed bellow, but let's have a look on the :ref:`installation process ` first.
.. _installation:
Installation
------------
On most UNIX-like systems, you’ll probably need to run these commands as root or using ``sudo``.
Install selenose using `setuptools `_/`distribute `_:
.. code-block:: bash
$ easy_install selenose
Or `pip `_:
.. code-block:: bash
$ pip install selenose
It can take a while as Selenium server's jar is downloaded on the fly during installation.
If you plan to use `django-jenkins `_, note that Django 1.4+ is required (`support for in-browser testing frameworks `_).
Nose
----
Selenose provides two `Selenium `_ related plugins for `nose `_:
* :ref:`selenium-server-plugin` starts a `Selenium Server `_ before running tests, and stops it at the end of the tests.
* :ref:`selenium-driver-plugin` provides a `Selenium Web Driver `_ to the tests.
.. _selenium-server-plugin:
Selenium Server Plugin
^^^^^^^^^^^^^^^^^^^^^^
This plugin starts a Selenium Server before running tests, and stops it at the end of the tests.
To enable it, add ``--with-selenium-server`` to the nose command line:
.. code-block:: bash
$ nose --with-selenium-server
You can also add the ``with-selenium-server`` option under the ``nosetests`` section of the configuration file (``setup.cfg``, ``~/.noserc`` or ``~/nose.cfg``):
.. code-block:: cfg
[nosetests]
with-selenium-server = true
Options for Selenium Server can be found by `downloading its jar `_ and typing:
.. code-block:: bash
$ java -jar /path/to/seleniumserver/libs/selenium-server-standalone-X.X.X.jar -h
Most common options are:
* ``-port ``: the port number the Selenium Server should use (default 4444),
* ``-log ``: writes lots of debug information out to a log file,
* ``-debug``: enable debug mode.
To set the server options, add a ``selenium-server`` section to the configuration file (``setup.cfg``, ``~/.noserc`` or ``~/nose.cfg``).
Option names are obtained by removing the initial dash, for instance to run:
.. code-block:: bash
$ java -jar selenium-server-standalone-X.X.X.jar -debug -log selenium-server.log
Add the following options to the configuration:
.. code-block:: cfg
[selenium-server]
debug = true
log = selenium-server.log
In your test, just create a new ``Remote`` Web Driver calling the server and that's it:
.. code-block:: python
import nose
import unittest
from selenium import webdriver
class TestCase(unittest.TestCase):
def test(self):
driver = webdriver.Remote(desired_capabilities=webdriver.DesiredCapabilities.FIREFOX)
try:
driver.get('http://www.google.com')
# Your test here...
finally:
driver.quit()
if __name__ == '__main__':
nose.main()
.. _selenium-driver-plugin:
Selenium Driver Plugin
^^^^^^^^^^^^^^^^^^^^^^
This plugin provides a Selenium Web Driver to Selenium tests.
Flag Selenium tests
+++++++++++++++++++
This plugin only provides Web Drivers to Selenium test. To declare a Selenium test:
* Either make your test case inherit from ``selenose.cases.SeleniumTestCase``,
* Or set a ``enable_selenium_driver`` flag to ``True``:
.. code-block:: python
class TestCase(unittest.TestCase):
enable_selenium_driver = True
Enable the plugin
+++++++++++++++++
To enable this plugin, add ``--with-selenium-driver`` on the nose command line:
.. code-block:: bash
$ nose --with-selenium-driver
You can also add the ``with-selenium-driver`` option under the ``nosetests`` section to the configuration file (``setup.cfg``, ``~/.noserc`` or ``~/nose.cfg``):
.. code-block:: cfg
[nosetests]
with-selenium-driver = true
But enabling it is not enough, a :ref:`web-driver-environment` is also required.
.. _web-driver-environment:
Web Driver environment
++++++++++++++++++++++
An environment declares all the necessary parameters to create a new Web Driver.
To create a new environment ``sample``, add a ``selenium-driver:sample`` section to the configuration file (``setup.cfg``, ``~/.noserc`` or ``~/nose.cfg``) with at least a ``webdriver`` option:
.. code-block:: cfg
[selenium-driver:sample]
webdriver = firefox
This ``webdriver`` option defines the Web Driver to use. Here are the available values:
* ``chrome`` for `Chrome `_, allowing the following options in configuration:
* ``executable_path`` (optional): path to ``chromedriver`` executable,
* ``port`` (optional),
* ``desired_capabilities`` (optional),
* ``firefox`` for `Firefox `_, allowing the following options in configuration:
* ``timeout`` (optional),
* ``ie`` for `Internet Explorer `_, allowing the following options in configuration:
* ``port`` (optional),
* ``timeout`` (optional),
* ``remote`` to delegate to a Selenium Server (started by :ref:`selenium-server-plugin`?), allowing the following options in configuration:
* ``command_executor`` (required): url of the server (``http://127.0.0.1:4444/wd/hub`` by default),
* ``desired_capabilities`` (required): the desired browser, it could be the lower case field name of ``selenium.webdriver.DesiredCapabilities`` such as ``firefox``, ``htmlunitwithjs``... or a comma separated key/value list such as ``browserName=firefox,platform=ANY``.
To enable an environment, add ``--selenium-driver`` on the nose command line:
.. code-block:: bash
$ nose --with-selenium-driver --selenium-driver=sample
You can also add the ``selenium-driver`` option under the ``nosetests`` section to the configuration file (``setup.cfg``, ``~/.noserc`` or ``~/nose.cfg``):
.. code-block:: cfg
[nosetests]
with-selenium-driver = true
selenium-driver = sample
[selenium-driver:sample]
webdriver = firefox
Selenose also provides a set of predefined but overridable environments:
.. code-block:: cfg
[selenium-driver:chrome]
webdriver = chrome
[selenium-driver:ie]
webdriver = ie
[selenium-driver:firefox]
webdriver = firefox
[selenium-driver:remote-htmlunit]
webdriver = remote
desired_capabilities = htmlunit
[selenium-driver:remote-htmlunitwithjs]
webdriver = remote
desired_capabilities = htmlunitwithjs
[selenium-driver:remote-opera]
webdriver = remote
desired_capabilities = opera
[selenium-driver:remote-...]
webdriver = remote
desired_capabilities = ...
Writing tests
+++++++++++++
The Web Driver is directly available with ``self.driver`` and there is no need to cleanup after use, selenose will do it for you:
.. code-block:: python
import nose
from selenose.cases import SeleniumTestCase
class TestCase(SeleniumTestCase):
def test(self):
self.driver.get('http://www.google.com')
# Your test here...
if __name__ == '__main__':
nose.main()
Combining Server & Driver
^^^^^^^^^^^^^^^^^^^^^^^^^
To combine a Selenium Server and a Selenium Driver plugin, just enable them both: the ``command_executor`` option of the ``remote`` Web Driver will know the correct value to reach the Selenium Server.
Django Jenkins
--------------
Selenose provides two `Selenium `_ related tasks for `django-jenkins `_:
* :ref:`selenium-server-task` starts a `Selenium Server `_ before running tests, and stops it at the end of the tests.
* :ref:`selenium-driver-task` provides a `Selenium Web Driver `_ to the tests.
Note that Django 1.4+ `support for in-browser testing frameworks `_ is required.
.. _selenium-server-task:
Selenium Server Task
^^^^^^^^^^^^^^^^^^^^
This task starts a Selenium Server before running tests, and stops it at the end of the tests.
To enable it, edit your ``settings.py`` and append ``selenose.tasks.selenium_server`` to ``JENKINS_TASKS``:
.. code:: python
JENKINS_TASKS = [
# Other tasks...
'selenose.tasks.selenium_server',
]
If this setting does not exist yet, do not forget to create it with the default tasks:
.. code:: python
JENKINS_TASKS = [
'django_jenkins.tasks.run_pylint',
'django_jenkins.tasks.with_coverage',
'django_jenkins.tasks.django_tests',
'selenose.tasks.selenium_server',
]
Options for Selenium Server are the same than for the nose :ref:`selenium-server-plugin`.
Set them in a ``setup.cfg`` located in the current working directory, for instance:
.. code-block:: cfg
[selenium-server]
debug = true
log = selenium-server.log
You can also specify the path to the configuration file with the ``--selenose-config`` option on the ``manage.py jenkins`` command line:
.. code:: bash
$ python manage.py jenkins --help
[...]
selenose.tasks.selenium_server:
--selenose-config=SELENOSE_CONFIGS
Load selenose configuration from config file(s). May
be specified multiple times; in that case, all config
files will be loaded and combined.
In your tests, just create a new ``Remote`` Web Driver calling the server and that's it:
.. code-block:: python
from django.test import LiveServerTestCase
from selenium import webdriver
class TestCase(LiveServerTestCase):
@classmethod
def setUpClass(cls):
cls.driver = webdriver.Remote(desired_capabilities=webdriver.DesiredCapabilities.FIREFOX)
super(BaseTestCase, cls).setUpClass()
@classmethod
def tearDownClass(cls):
super(BaseTestCase, cls).tearDownClass()
cls.driver.quit()
def test(self):
driver.get(self.live_server_url)
.. _selenium-driver-task:
Selenium Driver Task
^^^^^^^^^^^^^^^^^^^^
This task provides a Selenium Web Driver to Selenium tests.
To enable it, edit your ``settings.py`` and append ``selenose.tasks.selenium_driver`` to ``JENKINS_TASKS``:
.. code:: python
JENKINS_TASKS = [
# Other tasks...
'selenose.tasks.selenium_server',
]
If this setting does not exist yet, do not forget to create it with the default tasks:
.. code:: python
JENKINS_TASKS = [
'django_jenkins.tasks.run_pylint',
'django_jenkins.tasks.with_coverage',
'django_jenkins.tasks.django_tests',
'selenose.tasks.selenium_driver',
]
But enabling this task is not enough, a :ref:`web-driver-environment` is also required.
The :ref:`web-driver-environment` are defined in a ``setup.cfg`` located in the current working directory, for instance:
.. code-block:: cfg
[selenium-driver:sample]
webdriver = firefox
You can also specify the path to the configuration file containing the environments with the ``--selenose-config`` option on the ``manage.py jenkins`` command line:
.. code:: bash
$ python manage.py jenkins --help
[...]
selenose.tasks.selenium_driver:
--selenose-config=SELENOSE_CONFIGS
Load selenose configuration from config file(s). May
be specified multiple times; in that case, all config
files will be loaded and combined.
--selenium-driver=SELENIUM_DRIVER
Enable the provided environment.
To enable an environment, use the ``--selenium-driver`` option on the ``manage.py jenkins`` command line:
.. code:: bash
$ python manage.py jenkins --selenium-driver=sample
Then the Web Driver is directly available in you tests with ``self.driver`` and there is no need to cleanup after use, selenose will do it for you:
.. code-block:: python
from selenose.cases import LiveServerTestCase
class TestCase(LiveServerTestCase):
def test(self):
self.driver.get(self.live_server_url)
# Your test here...
Combining Server & Driver
^^^^^^^^^^^^^^^^^^^^^^^^^
To combine a Selenium Server and a Selenium Driver task, just enable them both in the settings: the ``command_executor`` option of the ``remote`` Web Driver will know the correct value to reach the Selenium Server.
.. code:: python
JENKINS_TASKS = [
# Other tasks...
'selenose.tasks.selenium_server',
'selenose.tasks.selenium_driver',
]
Tips
----
When writing tests, it's convenient to start a Selenium Server manually to reduce setup time when running tests. To do so, execute:
.. code-block:: bash
$ selenium-server
Starting... done!
Quit the server with CONTROL-C.
Then type ``CONTROL-C`` or ``CTRL-BREAK`` to stop the server.
In this case, run your tests neither with the :ref:`selenium-server-plugin` not with the :ref:`selenium-server-task`.