Add more documentation

docs/development.rst

@@ -17,6 +17,8 @@ another change to the pull branch.
 Running Tests
 -------------
 
-You will need `pytest <http://pytest.org/>`_ installed to run the tests::
+You will need `pytest <http://pytest.org/>`_ installed to run the tests:
 
-  py.test testing
+.. code-block:: bash
+
+  $ py.test testing

docs/installing.rst

@@ -9,10 +9,14 @@ pytest-selenium requires Python 2.6 or 2.7.
 Install pytest-selenium
 -----------------------
 
-To install pytest-selenium using `pip <https://pip.pypa.io/>`_::
+To install pytest-selenium using `pip <https://pip.pypa.io/>`_:
 
-  pip install pytest-selenium
+.. code-block:: bash
 
-To install from source::
+  $ pip install pytest-selenium
 
-  python setup.py develop
+To install from source:
+
+.. code-block:: bash
+
+  $ python setup.py develop

docs/user_guide.rst

@@ -1,58 +1,142 @@
 User Guide
 ==========
 
-.. contents::
+.. contents:: :depth: 3
+
+Quick Start
+***********
+
+The pytest-selenium plugin provides a method scoped selenium
+`fixture <http://pytest.org/latest/fixture.html>`_ for your tests. This means
+that any test with selenium as an argument will cause a browser instance to be
+invoked. The browser may run locally or remotely depending on your
+configuration, and may even run headless.
+
+Here's a simple example test that opens a website using Selenium:
+
+.. code-block:: python
+
+  def test_example(selenium):
+      selenium.get('http://www.example.com')
+
+To run the above test you will need to specify the browser instance to be
+invoked. For example, to run it using Firefox installed in a default location:
+
+
+.. code-block:: bash
+
+  $ py.test --driver Firefox
+
+For full details of the Selenium API you can refer to the official
+documentation. [LINK TO SELENIUM API]
+
+Specifying a Base URL
+*********************
+
+Rather than repeating or abstracting the base URL in your tests, pytest-selenium
+also provides a base_url fixture that by default will return a value specified
+on the command line.
+
+Here's the earlier example with the addition of base_url:
+
+.. code-block:: python
+
+  def test_example(base_url, selenium):
+      selenium.get('%{0}'.format(base_url))
+
+The associated command line would be:
+
+.. code-block:: bash
+
+  $ py.test --base-url http://www.example.com --driver Firefox
+
+Dynamic Base URLs
+-----------------
+
+If your test harness takes care of launching an instance of your application
+under test, you may not have a predictable base URL to provide on the command
+line. Fortunately, it's easy to override the base_url fixture and return the
+correct URL to your test.
+
+.. code-block:: python
+
+  import pytest
+  @pytest.fixture
+  def base_url(liveserver):
+      # liveserver is a fixture that takes care of starting your application,
+      # your chosen framework may already provide one of these for your
+      # integration tests
+      return liveserver.url
+
+  def test_search(base_url, selenium):
+      selenium.get('%{0}/search'.format(base_url))
+
+Specifying a Browser
+********************
+
+To indicate the browser you want to run your tests against you will need to
+specify a driver and optional capabilties.
 
 Firefox
-*******
+-------
+
+To run your automated tests with Firefox, specify ``Firefox`` as your driver:
 
-To run your automated tests with Firefox, specify ``Firefox`` as your driver::
+.. code-block:: bash
 
-  py.test --driver Firefox
+  $ py.test --driver Firefox
 
 Chrome
-******
+------
 
 To use Chrome as the driver, you need to have ChromeDriver installed. You can
 download it
 `here <https://sites.google.com/a/chromium.org/chromedriver/downloads>`_.
 You may either download ChromeDriver to a location in your PATH, or utilize
 the option to specify the driver path during test execution.
 
-To run your automated tests, specify ``Chrome`` as your driver::
+To run your automated tests, specify ``Chrome`` as your driver:
+
+.. code-block:: bash
 
-  py.test --driver Chrome
+  $ py.test --driver Chrome
 
 If ChromeDriver is not on your path, use ``--driver-path`` to specify the
-location::
+location:
 
-  py.test --driver Chrome --driver-path /path/to/chromedriver
+.. code-block:: bash
+
+  $ py.test --driver Chrome --driver-path /path/to/chromedriver
 
 For more information relating to ChromeDriver, you may read its documentation
 `here <https://sites.google.com/a/chromium.org/chromedriver/>`_.
 
 PhantomJS
-*********
+---------
 
 To use PhantomJS as the driver, you need to have it installed. You can download
 it `here <http://phantomjs.org/download.html>`_.
 You may either download PhantomJS to a location in your PATH, or utilize
 the option to specify the driver path during test execution.
 
-To run your automated tests, specify ``PhantomJS`` as your driver::
+To run your automated tests, specify ``PhantomJS`` as your driver:
+
+.. code-block:: bash
 
-  py.test --driver PhantomJS
+  $ py.test --driver PhantomJS
 
 If PhantomJS is not on your path, use ``--driver-path`` to specify the
-location::
+location:
+
+.. code-block:: bash
 
-  py.test --driver PhantomJS --driver-path /path/to/phantomjs
+  $ py.test --driver PhantomJS --driver-path /path/to/phantomjs
 
 For more information relating to PhantomJS, you may read its documentation
 `here <http://phantomjs.org/quick-start.html>`_.
 
 Selenium Server/Grid
-********************
+--------------------
 
 To run your automated tests against a
 `Selenium server <https://github.com/SeleniumHQ/selenium/wiki/RemoteWebDriverServer>`_
@@ -68,27 +152,30 @@ selection is determined using capabilities. Check the
 for details of accepted values. There are also a number of
 `browser specific capabilities <https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities#browser-specific-capabilities>`_
 that can be set. Be sure to also check the documentation for your chosen
-driver, as the accepted capabilities may differ::
+driver, as the accepted capabilities may differ:
+
+.. code-block:: bash
 
-  py.test --driver Remote --capability browserName firefox
+  $ py.test --driver Remote --capability browserName firefox
 
 Note that if your server is not running locally or is running on an alternate
 port you will need to specify the ``--host`` and ``--port`` command line
-options::
+options:
 
-  py.test --driver Remote --host selenium.hostname --port 5555 --capability browserName firefox
+.. code-block:: bash
 
+  $ py.test --driver Remote --host selenium.hostname --port 5555 --capability browserName firefox
 
 Sauce Labs
-**********
+----------
 
 To run your automated tests using `Sauce Labs <https://saucelabs.com/>`_, you
 must provide a valid username and API key. This can be done either by using
 a ``setup.cfg`` file or by setting the ``SAUCELABS_USERNAME`` and
 ``SAUCELABS_API_KEY`` environment variables.
 
 Configuration
--------------
+~~~~~~~~~~~~~
 
 Below is an example ``setup.cfg`` showing the configuration options:
 
@@ -106,11 +193,13 @@ accepted values. If not set, this defaults to
 `public restricted <https://saucelabs.com/docs/additional-config#restricted>`_.
 
 Running tests
--------------
+~~~~~~~~~~~~~
+
+To run your automated tests, simply specify ``SauceLabs`` as your driver:
 
-To run your automated tests, simply specify ``SauceLabs`` as your driver::
+.. code-block:: bash
 
-  py.test --driver SauceLabs --capability browserName Firefox
+  $ py.test --driver SauceLabs --capability browserName Firefox
 
 See the `supported platforms <https://docs.saucelabs.com/reference/platforms-configurator/>`_
 to help you with your configuration. Additional capabilities can be set using
@@ -119,7 +208,7 @@ the ``--capability`` command line arguments. See the
 for full details of what can be configured.
 
 Job visibility
---------------
+~~~~~~~~~~~~~~
 
 You can specify the job sharing level for individual tests by setting a mark on
 the test method. This takes priority over the ``sauce_labs_job_visibility``
@@ -145,7 +234,7 @@ For the full list of accepted values, check the
 `Sauce Labs documentation <https://saucelabs.com/docs/additional-config#sharing>`_.
 
 BrowserStack
-************
+------------
 
 To run your automated tests using
 `BrowserStack <https://www.browserstack.com/>`_, you must provide a valid
@@ -154,7 +243,7 @@ or by setting the ``BROWSERSTACK_USERNAME`` and ``BROWSERSTACK_ACCESS_KEY``
 environment variables.
 
 Configuration
--------------
+~~~~~~~~~~~~~
 
 Below is an example ``setup.cfg`` showing the configuration options:
 
@@ -165,19 +254,21 @@ Below is an example ``setup.cfg`` showing the configuration options:
   browserstack_access_key = secret
 
 Running tests
--------------
+~~~~~~~~~~~~~
 
-To run your automated tests, simply specify ``BrowserStack`` as your driver::
+To run your automated tests, simply specify ``BrowserStack`` as your driver:
 
-  py.test --driver BrowserStack --capability browserName Firefox
+.. code-block:: bash
+
+  $ py.test --driver BrowserStack --capability browserName Firefox
 
 See the
 `capabilities documentation <https://www.browserstack.com/automate/capabilities>`_
 for additional configuration that can be set using ``--capability`` command line
 arguments.
 
 Capabilities
-************
+------------
 
 Configuration options are specified using a capabilities dictionary. This is
 required when using a Selenium server to specify the target environment, but
@@ -197,9 +288,11 @@ The following is an example of a variables file including capabilities:
       "platform": "MAC" }
   }
 
-Simple capabilities can be set or overridden on the command line::
+Simple capabilities can be set or overridden on the command line:
+
+.. code-block:: bash
 
-  py.test --driver Remote --capability browserName Firefox
+  $ py.test --driver Remote --capability browserName Firefox
 
 You can also add or change capabilities by overwriting the ``capabilities``
 fixture:
@@ -211,3 +304,18 @@ fixture:
   def capabilities(capabilities):
       capabilities['tags'] = ['tag1', 'tag2', 'tag3']
       return capabilities
+
+Common Selenium Setup
+*********************
+
+If you have common setup that you want to apply to your tests, such as setting
+the implicit timeout or window size, you can override the ``selenium`` fixture:
+
+.. code-block:: python
+
+  import pytest
+  @pytest.fixture
+  def selenium(selenium):
+      selenium.implicitly_wait(10)
+      selenium.maximize_window()
+      return selenium