lxml testcase area
==================

If you discover what you think is a bug in lxml, it is often nice to
have test cases so the developers can reproduce their bug. This area
is a place where you can check in such testcases.

There are two procedures, one for test cases in a directory, and one
for those who want to write unit tests directly (preferred).

Test cases
----------

The procedure to follow is as follows:

* Each person puts their testcases in a directory the same as their
  codespeak username. I would for instance use the 'faassen'
  directory.

* Put each failing testcase in a separate directory underneath. A
  testcase would be composed of some python code to run (let's call it
  'main.py'), and possibly some XML documents that it needs.

* Put in a README.txt in that directory describing what is going on,
  and what you think should happen instead.

* Mail to the lxml-dev list describing the problem and refer to the
  svn directory.

Please keep your testcase as short as possible to make life easy for
the lxml developers; if you check in big pieces of software here the
lxml developers may be too daunted to figure it out.

Please make it as easy as possible for the lxml developers to run your
testcase. So, provide a module that can be easily run, instead of
requiring the developer write code just to run your testcase.

The lxml developers will typically try to translate the problem to a
brief unit test that will become part of the lxml testsuite. If that
is done and the problem has been resolved, the lxml developers may
clean out the testcase from this area of the repository. 

You may want to decide to write a unit test directly if you're
comfortable in doing so. That would make the lxml developer's life
easiest of all. See the next section for details on what procedure to take.

Unit tests
----------

By 'unit test' we mean tests can can be run using the Python unit test
framework. For examples, see the 'tests' directory in the lxml package
itself.

There is a special directory called 'unittests' in which you can place
a file called test_<your username>.py. An example you can copy to get
started is test_faassen.py. Add new tests to your own file, though if
you ever need a second one, add a number behind it, like
test_faassen2.py.

When you add a failing unit test, describe in the code what you
expect, and also post a pointer to the lxml mailing list, describing
the problem. This way the developers can take a look at it and discuss
it. If the lxml developers determine this is indeed a real bug, the
test will be moved into lxml's test suite and the test will be
fixed. We hope therefore there will never be many tests in the
testcase package itself.

It's okay to add failing tests in here; the point is to communicate,
and this is not the official test suite for lxml. We do *not* want any
failing tests added to the lxml test suite itself though -- failing
tests there should never be checked in, so that a checkout of lxml
always has functional tests.