<commit_before>.. _testing:

************************
PySAL Testing Procedures
************************

All public classes and functions should include examples in their docstrings. Those examples serve two purposes:

#. Documentation for users
#. Tests to ensure code behavior is aligned with the documentation

To ensure that any changes made to one module do not introduce breakage in the wider project, developers should run the
package wide test script in `tests/tests.py <http://code.google.com/p/pysal/source/browse/trunk/pysal/tests/tests.py>`_ before making any commits.

The trunk should most always be in a state where all tests are passed.


Package-wide tests for PySAL
============================


Currently allows for testing of docstring examples from individual modules.
Prior to commiting any changes to the trunk, said changes should be checked
against the rest of the local copy of the trunk by running::

    python tests.py

If all tests pass, changes have not broken the current trunk and can be
committed. Commits that introduce breakage should only be done in cases where
other developers are notified and the breakage raises important issues for
discussion.


Notes
=====
New modules need to be included in the `#module imports` section, as
well as in the truncated module list where `mods` is first defined.

To deal with relative paths in the doctests a symlink must first be made from
within the `tests` directory as follows::

     ln -s ../examples .

<commit_msg>- update testing instructions for new integration testing<commit_after>.. _testing:

************************
PySAL Testing Procedures
************************

PySAL relies on two different modes of testing [1] integration (regression)
testing and [2] doctests. All developers responsible for given packages shall
utilize both modes.

Integration Testing
===================

Each package shall have a directory `tests` in which unit tests scripts for
each module in the package directory are required. 

For example, in the directory `pysal/esda` the module `moran.py` requires a
unittest script named `test_moran.py`. This path for this script needs to be
`pysal/esda/tests/test_moran.py`.

To ensure that any changes made to one package/module do not introduce breakage in the wider project, developers should run the
package wide test script in `tests/tests.py <http://code.google.com/p/pysal/source/browse/trunk/pysal/tests/tests.py>`_ before making any commits.

This script will run any existing unit tests as well as identify packages
missing any tests.

The trunk should most always be in a state where all tests are passed.

Docstrings and Doctests
=======================

All public classes and functions should include examples in their docstrings. Those examples serve two purposes:

#. Documentation for users
#. Tests to ensure code behavior is aligned with the documentation

Doctests will be executed when buidling PySAL documentation with Sphinx.



Notes
=====
When writing any unittests that pull examples from `pysal/examples` be sure that
the path is relative to the `pysal/tests` directory.

For example, if a test in `pysal/esda/tests/test_moran.py` uses data from
`pysal/examples/filename` the appropriate path in the `test_moran.py` file should be
`path="../examples/filename"` not `path="../../examples/filename"` since the
system wide tests are run from within `pysal/tests`


{'fraction_non_alphanumeric': 0.10252643948296122, 'fraction_numerical': 0.0005875440658049354, 'mean_word_length': 4.665557404326123, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6625189', 'n_tokens_mistral': 890, 'n_tokens_neox': 835, 'n_words': 450}