<commit_before>.. -*- rest -*-

NumPy/SciPy Testing Guidelines
==============================

.. contents::

Introduction
''''''''''''

SciPy uses the `Nose testing system
<http://www.somethingaboutorange.com/mrl/projects/nose>`__, with some
minor convenience features added.  Nose is an extension of the unit
testing framework offered by `unittest.py
<http://docs.python.org/lib/module-unittest.html>`__. Our goal is that
every module and package in SciPy should have a thorough set of unit
tests. These tests should exercise the full functionality of a given
routine as well as its robustness to erroneous or unexpected input
arguments. Long experience has shown that by far the best time to
write the tests is before you write or change the code - this is
`test-driven development
<http://en.wikipedia.org/wiki/Test-driven_development>`__.  The
arguments for this can sound rather abstract, but we can assure you
that you will find that writing the tests first leads to more robust
and better designed code. Well-designed tests with good coverage make
an enormous difference to the ease of refactoring. Whenever a new bug
is found in a routine, you should write a new test for that specific
case and add it to the test suite to prevent that bug from creeping
back in unnoticed.

To run SciPy's full test suite, use the following::

  >>> import scipy
  >>> scipy.test()

SciPy uses the testing framework from NumPy (specifically
``numpy.testing``), so all the SciPy examples shown here are also
applicable to NumPy.  So NumPy's full test suite can be run as
follows::

  >>> import numpy
  >>> numpy.test()

The test method may take two or more arguments; the first, ``label`` is a
string specifying what should be tested and the second, ``verbose`` is an
integer giving the level of output verbosity. See the docstring for
numpy.test for details.  The default value for ``label`` is 'fast' - which
will run the standard tests.  The string 'full' will run the full battery
of tests, including those identified as being slow to run. If ``verbose``
is 1 or less, the tests will just show information messages about the tests
that are run; but if it is greater than 1, then the tests will also provide
warnings on missing tests. So if you want to run every test and get
messages about which modules don't have tests::

  >>> scipy.test(label='full', verbose=2) # or scipy.test('full', 2)

Finally, if you are only interested in testing a subset of SciPy, for
example, the ``integrate`` module, use the following::

>>> scipy.integrate.test()

The rest of this page will give you a basic idea of how to add unit
tests to modules in SciPy. It is extremely important for us to have
extensive unit testing since this code is going to be used by
scientists and researchers and is being developed by a large number of
people spread across the world. So, if you are writing a package that
you'd like to become part of SciPy, please write the tests as you
develop the package. Also since much of SciPy is legacy code that was
originally written without unit tests, there are still several modules
that don't have tests yet. Please feel free to choose one of these
modules and develop tests for it as you read through
this introduction.

Writing your own tests
''''''''''''''''''''''

Every Python module, extension module, or subpackage in the SciPy
package directory should have a corresponding ``test_<name>.py`` file.
Nose examines these files for test methods (named test*) and test
classes (named Test*).

Suppose you have a SciPy module ``scipy/xxx/yyy.py`` containing a
function ``zzz()``.  To test this function you would create a test
module called ``test_yyy.py``.  If you only need to test one aspect of
``zzz``, you can simply add a test function::

  def test_zzz():
      assert_(zzz() == 'Hello from zzz')

More often, we need to group a number of tests together, so we create
a test class::

  from numpy.testing import assert_, assert_raises

  # import xxx symbols
  from scipy.xxx.yyy import zzz

  class TestZzz:
      def test_simple(self):
          assert_(zzz() == 'Hello from zzz')

      def test_invalid_parameter(self):
          assert_raises(...)

Within these test methods, ``assert_()`` and related functions are used to test
whether a certain assumption is valid. If the assertion fails, the test fails.
Note that the Python builtin ``assert()`` should not be used, because it is
stripped during compilation with ``-O``.

Note that ``test_`` functions or methods should not have a docstring, because
that makes it hard to identify the test from the output of running the test
suite with ``verbose=2`` (or similar verbosity setting).  Use plain comments
(``#``) if necessary.

Sometimes it is convenient to run ``test_yyy.py`` by itself, so we add

::

  if __name__ == "__main__":
      run_module_suite()
<commit_msg>DOC:Revert ``assert()`` back to ``assert`` (statement)<commit_after>.. -*- rest -*-

NumPy/SciPy Testing Guidelines
==============================

.. contents::

Introduction
''''''''''''

SciPy uses the `Nose testing system
<http://www.somethingaboutorange.com/mrl/projects/nose>`__, with some
minor convenience features added.  Nose is an extension of the unit
testing framework offered by `unittest.py
<http://docs.python.org/lib/module-unittest.html>`__. Our goal is that
every module and package in SciPy should have a thorough set of unit
tests. These tests should exercise the full functionality of a given
routine as well as its robustness to erroneous or unexpected input
arguments. Long experience has shown that by far the best time to
write the tests is before you write or change the code - this is
`test-driven development
<http://en.wikipedia.org/wiki/Test-driven_development>`__.  The
arguments for this can sound rather abstract, but we can assure you
that you will find that writing the tests first leads to more robust
and better designed code. Well-designed tests with good coverage make
an enormous difference to the ease of refactoring. Whenever a new bug
is found in a routine, you should write a new test for that specific
case and add it to the test suite to prevent that bug from creeping
back in unnoticed.

To run SciPy's full test suite, use the following::

  >>> import scipy
  >>> scipy.test()

SciPy uses the testing framework from NumPy (specifically
``numpy.testing``), so all the SciPy examples shown here are also
applicable to NumPy.  So NumPy's full test suite can be run as
follows::

  >>> import numpy
  >>> numpy.test()

The test method may take two or more arguments; the first, ``label`` is a
string specifying what should be tested and the second, ``verbose`` is an
integer giving the level of output verbosity. See the docstring for
numpy.test for details.  The default value for ``label`` is 'fast' - which
will run the standard tests.  The string 'full' will run the full battery
of tests, including those identified as being slow to run. If ``verbose``
is 1 or less, the tests will just show information messages about the tests
that are run; but if it is greater than 1, then the tests will also provide
warnings on missing tests. So if you want to run every test and get
messages about which modules don't have tests::

  >>> scipy.test(label='full', verbose=2) # or scipy.test('full', 2)

Finally, if you are only interested in testing a subset of SciPy, for
example, the ``integrate`` module, use the following::

>>> scipy.integrate.test()

The rest of this page will give you a basic idea of how to add unit
tests to modules in SciPy. It is extremely important for us to have
extensive unit testing since this code is going to be used by
scientists and researchers and is being developed by a large number of
people spread across the world. So, if you are writing a package that
you'd like to become part of SciPy, please write the tests as you
develop the package. Also since much of SciPy is legacy code that was
originally written without unit tests, there are still several modules
that don't have tests yet. Please feel free to choose one of these
modules and develop tests for it as you read through
this introduction.

Writing your own tests
''''''''''''''''''''''

Every Python module, extension module, or subpackage in the SciPy
package directory should have a corresponding ``test_<name>.py`` file.
Nose examines these files for test methods (named test*) and test
classes (named Test*).

Suppose you have a SciPy module ``scipy/xxx/yyy.py`` containing a
function ``zzz()``.  To test this function you would create a test
module called ``test_yyy.py``.  If you only need to test one aspect of
``zzz``, you can simply add a test function::

  def test_zzz():
      assert_(zzz() == 'Hello from zzz')

More often, we need to group a number of tests together, so we create
a test class::

  from numpy.testing import assert_, assert_raises

  # import xxx symbols
  from scipy.xxx.yyy import zzz

  class TestZzz:
      def test_simple(self):
          assert_(zzz() == 'Hello from zzz')

      def test_invalid_parameter(self):
          assert_raises(...)

Within these test methods, ``assert_()`` and related functions are used to test
whether a certain assumption is valid. If the assertion fails, the test fails.
Note that the Python builtin ``assert`` should not be used, because it is
stripped during compilation with ``-O``.

Note that ``test_`` functions or methods should not have a docstring, because
that makes it hard to identify the test from the output of running the test
suite with ``verbose=2`` (or similar verbosity setting).  Use plain comments
(``#``) if necessary.

Sometimes it is convenient to run ``test_yyy.py`` by itself, so we add

::

  if __name__ == "__main__":
      run_module_suite()

{'fraction_non_alphanumeric': 0.08152565025187622, 'fraction_numerical': 0.0010280662074637606, 'mean_word_length': 4.218884120171674, 'pattern_counts': {'":': 2, '<': 11, '<?xml version=': 0, '>': 47, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3576850', 'n_tokens_mistral': 2633, 'n_tokens_neox': 2534, 'n_words': 1449}