\
Flunc: a functional test suite runner for web applications.
Installation
============
We recommend installing into a Virtualenv_.
You should be able to install flunc by using ``easy_install flunc``; or
you can download the tarball, extract, and run ``python setup.py develop``.
Writing tests
=============
Flunc tests are Twill_ scripts.
There is a firefox extension that allows you to record tests directly
from within your browser. To install, visit
* http://sourceforge.net/projects/testgen4web/
These tests are saved in an xml format. You can convert these tests
into a twill script by executing
``testgentotwill recorded.html > twillscript.twill``
Of course, you can still write tests manually.
Running tests
=============
Run ``flunc --help`` for details on running the functional tests.
By default flunc will search ./ftests/ to find tests. You can change
this with the ``-p`` (``--path``) option.
Some examples:
``flunc all``
runs all tests listed in all.tsuite against http://localhost/
``flunc -t http://localhost:8080/some_portal all``
runs all tests listed in all.tsuite against localhost:8080/some_portal
``flunc -c all create_user``
runs create_user.twill using all.conf
``flunc -c all create_user login create_project destroy_project destroy_user``
specify an ad hoc suite creating and tearing down a user and project
on default host
Finding tests
=============
Individual tests are contained in
<test>.twill
A suite of tests are contained in
<suite>.tsuite
Suite configurations are contained in
<suite>.conf
Cleanup suites are run after a suite, and are in
<suite>_cleanup.tsuite
More details are on the `Flunc homepage`_.
.. _Virtualenv: http://pypi.python.org/pypi/virtualenv
.. _Twill: http://pypi.python.org/pypi/twill
.. _`Flunc homepage`: http://www.coactivate.org/projects/flunc
0.8 (2011-04-04)
================
* Better behavior for the error case where search path (-p option)
is nonexistent or not a directory (egj)
* Add optional second argument to `url_qs` command in flunc.urlinspector
which, if present, asserts the value of the given querystring parameter,
as well as asserting its presence. (egj)
* Add new command `css_len` in flunc.xpath which lets you test that
a given CSS selector matches exactly N elements in the page (egj)
0.7 (2009-10-05)
================
* The -D (--define) command-line option now works as documented (egj)
0.6 (2009-07-06)
================
* Add extension module flunc.urlinspector with a command `url_qs` for
making simple assertions about the current url's query string (egj)
* Add `notfind_in_css` command to flunc.xpath (egj)
* Display a more meaningful error message for invalid argument-passing
syntaxes (egj)
* Add a `zope_cleanup.opencore_user_cleanup` method to flush the opencore
member cleanup queue when deleting users. No hard failure if you have a
version of opencore that doesn't support this (pw)
0.5 (2009-05-05)
================
* Add `find_in_css` command to flunc.xpath module. Use it to find a regex
within a given CSS selector, like find_in_xpath (egj)
* Transfer binary data directly to the twill script for passed-in param
values instead of escaping it as a string (cabraham)
0.4 (2008-12-18)
================
* Add two twill extensions to checkbox.py: `not_selected`, `is_enabled` (pw)
* Change is_selected to work correctly with checkboxes, I think (pw)
* Change default host to http://localhost (pw)
0.3 (2008-06-25)
================
* Add a twill extension (flunc.checkbox.is_selected) for making assertions
about form defaults (pw)
0.2 (2008-04-14)
================
* Don't display BadRequest exceptions when calling zope_delobject() -- those
are normal and just add a lot of noise (pw)
* Added twill extension to support xpath. This introduces a dependency on lxml.
There is one function added: find_in_xpath (rmarianski)
find_in_xpath runs a find command on the html result of an xpath expression
For example:
{{{
extend_with flunc.xpath
find_in_xpath "People" "//div[@id='oc-pageNav']"
}}}
* Altered the namespace behavior; now there is no leading dot to
specify the global namespace. (jhammel)
Instead, we use a scope-based model:
1. items (tests, suites, configuration) is first looked up relavent to
the current (local) namespace
2. if they are not found locally, they are looked up in the global namespace
The dot is still used for namespace separation. So looking up foo.bar
will first look for the namespace foo in the local namespace; if this
exists, it will try to look up bar in that. If foo is not a namespace
relavent to the current one, it will try to look up foo.bar in the
global namespace.
* Added hierarchal namespaces to tests (jhammel)
Formerly, tests lived in a flat namespace. Using --recursive, one
could put all tests under the root directory into a single namespace.
Now each directory has a namespace associated with it. Tests or
suites with single names refer to items in the same namespace (that
is, the same directory). You may refer to the bar test or suite in
the foo subdirectory as
foo.bar
If a suite has the same name as the subdirectory name, you may refer
to it either with the full specification
foo.foo
or with shorthand
foo
To refer to the global namespace, preface the name of the test, suite,
or path with a dot
.foo.bar
refers to the bar suite or test under the foo directory under the root
directory.
These changes should be backwards compatible with existing tests and
were made to facilitate test organization with the hope of providing
the flexibility to manipulate namespaces when tests live in multiple
locations on disc.