==========================

Use Windmill with CubicWeb

==========================

Windmill_ implements cross browser testing, in-browser recording and playback,

and functionality for fast accurate debugging and test environment integration.

.. _Windmill: http://www.getwindmill.com/

`Online features list <http://www.getwindmill.com/features>`_ is available.

Installation

============

Windmill

--------

You have to install Windmill manually for now. If you're using Debian, there is

no binary package (`yet <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=579109>`_).

The simplest solution is to use a *setuptools/pip* command (for a clean

environment, take a look to the `virtualenv

<http://pypi.python.org/pypi/virtualenv>`_ project as well)::

    $ pip install windmill

    $ curl -O http://github.com/windmill/windmill/tarball/master

However, the Windmill project doesn't release frequently. Our recommandation is

to used the last snapshot of the Git repository::

    $ git clone git://github.com/windmill/windmill.git HEAD

    $ cd windmill

    $ python setup.py develop

Install instructions are `available <http://wiki.github.com/windmill/windmill/installing>`_.

Be sure to have the windmill module in your PYTHONPATH afterwards::

    $ python -c "import windmill"

X dummy

-------

In order to reduce unecessary system load from your test machines, It's

recommended to use X dummy server for testing the Unix web clients, you need a

dummy video X driver (as xserver-xorg-video-dummy package in Debian) coupled

with a light X server as `Xvfb <http://en.wikipedia.org/wiki/Xvfb>`_.

    The dummy driver is a special driver available with the XFree86 DDX. To use

    the dummy driver, simply substitue it for your normal card driver in the

    Device section of your xorg.conf configuration file. For example, if you

    normally uses an ati driver, then you will have a Device section with

    Driver "ati" to let the X server know that you want it to load and use the

    ati driver; however, for these conformance tests, you would change that

    line to Driver "dummy" and remove any other ati specific options from the

    Device section.

    *From: http://www.x.org/wiki/XorgTesting*

Then, you can run the X server with the following command ::

    $ /usr/bin/X11/Xvfb :1 -ac -screen 0 1280x1024x8 -fbdir /tmp

Windmill usage

==============

Record your use case

--------------------

- start your instance manually

- start Windmill_ with url site as last argument (read Usage_ or use *'-h'*

  option to find required command line arguments)

- use the record button

- click on save to obtain python code of your use case

- copy the content to a new file in a *windmill* directory

.. _Usage: http://wiki.github.com/windmill/windmill/running-tests

If you are using firefox as client, consider the "firebug" option.

If you have a running instance, you can refine the test by the *loadtest* windmill option::

    $ windmill -m firebug loadtest=<test_file.py> <instance url>

Or use the internal windmill shell to explore available commands::

    $ windmill -m firebug shell <instance url>

And enter python commands:

.. sourcecode:: python

    >>> load_test(<your test file>)

    >>> run_test(<your test file>)

Integrate Windmill tests into CubicWeb

======================================

Set environment

---------------

You have to create a new unit test file and a `windmill` directory and copy all

your windmill use case into it.

.. sourcecode:: python

    # test_windmill.py

    # Run all scenarii found in windmill directory

    from cubicweb.devtools.cwwindmill import (CubicWebWindmillUseCase,

                                              unittest_main)

    if __name__ == '__main__':

        unittest_main()

Run your tests

--------------

You can easily run your windmill test suite through `pytest` or :mod:`unittest`.

You have to copy a *test_windmill.py* file from :mod:`web.test`.

To run your test series::

    $ pytest test/test_windmill.py

By default, CubicWeb will use **firefox** as the default browser and will try

to run test instance server on localhost. In the general case, You've no need

to change anything.

Check :class:`cubicweb.devtools.cwwindmill.CubicWebWindmillUseCase` for

Windmill configuration. You can edit windmill settings with following class attributes:

* browser

  identification string (firefox|ie|safari|chrome) (firefox by default)

* test_dir

  testing file path or directory (windmill directory under your unit case

  file by default)

* edit_test

  load and edit test for debugging (False by default)

Examples:

.. sourcecode:: python

    browser = 'firefox'

    test_dir = osp.join(__file__, 'windmill')

    edit_test = False

If you want to change cubicweb test server parameters, you can check class

variables from :class:`CubicWebServerConfig` or inherit it with overriding the

:attr:`configcls` attribute in :class:`CubicWebServerTC` ::

.. sourcecode:: python

    class OtherCubicWebServerConfig(CubicWebServerConfig):

        port = 9999

    class NewCubicWebServerTC(CubicWebServerTC):

        configcls = OtherCubicWebServerConfig

For instance, CubicWeb framework windmill tests can be manually run by::

    $ pytest web/test/test_windmill.py

Edit your tests

---------------

You can toggle the `edit_test` variable to enable test edition.

But if you are using `pytest` as test runner, use the `-i` option directly.

The test series will be loaded and you can run assertions step-by-step::

    $ pytest -i test/test_windmill.py

In this case, the `firebug` extension will be loaded automatically for you.

Afterwards, don't forget to save your edited test into the right file (no autosave feature).

Best practises

--------------

Don't run another instance on the same port. You risk to silence some

regressions (test runner will automatically fail in further versions).

Start your use case by using an assert on the expected primary url page.

Otherwise all your tests could fail without clear explanation of the used

navigation.

In the same location of the *test_windmill.py*, create a *windmill/* with your

windmill recorded use cases.

Caveats

=======

File Upload

-----------

Windmill can't do file uploads. This is a limitation of browser Javascript

support / sandboxing, not of Windmill per se.  It would be nice if there were

some command that would prime the Windmill HTTP proxy to add a particular file

to the next HTTP request that comes through, so that uploads could at least be

faked.

.. http://groups.google.com/group/windmill-dev/browse_thread/thread/cf9dc969722bd6bb/01aa18fdd652f7ff?lnk=gst&q=input+type+file#01aa18fdd652f7ff

.. http://davisagli.com/blog/in-browser-integration-testing-with-windmill

.. http://groups.google.com/group/windmill-dev/browse_thread/thread/b7bebcc38ed30dc7

Preferences

===========

A *.windmill/prefs.py* could be used to redefine default configuration values.

.. define CubicWeb preferences in the parent test case instead with a dedicated firefox profile

For managing browser extensions, read `advanced topic chapter

<http://wiki.github.com/windmill/windmill/advanced-topics>`_.

More configuration examples could be seen in *windmill/conf/global_settings.py*

as template.