Testing

Important: make sure to document failure conditions (and use the assertRaisesRegexp where necessary to make it clearer which exception you want to get).

Testing for Exceptions

Generally, it's not acceptable to just check that something raises Exception, because that tends to mask a lot of errors. For example, if a function's signature changes between releases, you could be catching the wrong kind of error altogether.

Another element that is helpful is to use assertRaisesRegexp from pandas.util.testing, which allows you to specify a regular expression to match against. The call signature is nearly the same as assertRaises, but it adds an extra positional argument E.g.

assertRaisesRegexp(TypeError, 'literal', int, 'XYZ')
# or another common possibility (originally was PandasError, now changed.)
assertRaisesRegexp(TypeError, 'constructor', DataFrame, 1)

Handling tests requiring network connectivity

In general, network tests are finicky. All tests that involve networking must be marked as "network", either by using the network decorator or the with_connectivity_check decorator from pandas.util.testing.Unless you absolutely need to test that a function/method correctly handles connectivity errors, you should use the network decorator, which will catch all IOErrors (which includes URLError). If you believe that your test case will only fail if you simply aren't connected to the internet, you can use the with_connectivity_test to check:

>>> @with_connectivity_test
... def test_my_function():
...     urllib2.urlopen("funny://rabbithead")
>>> test_my_function()
Traceback (most recent call last)
    ...
URLError...#some message

If you want to have the decorator always raise errors, just pass raise_on_error=True to the network decorator:

>>> @network(raise_on_error=True)
... def test2():
...     raise URLError("WRONG!")
Traceback (most recent call last)
    ...
URLError: WRONG!

Testing for Warnings

To test for warnings, you can use the assert_produces_warning contextmanager, which checks that your code produces a warning.

Probably the most common case is just a test case for a DeprecationWarning:

>>> with assert_produces_warning(DeprecationWarning):
...     some_function_that_raises_deprecation_warning()

With no arguments, it checks that any warning is raised.

    >>> import warnings
    >>> with assert_produces_warning():
    ...     warnings.warn(UserWarning())
    ...

When passed False, it checks that no warnings are raised.

    >>> with assert_produces_warning(False):
    ...     warnings.warn(RuntimeWarning())
    ...
    Traceback (most recent call last):
        ...
    AssertionError: Caused unexpected warning(s): ['RuntimeWarning'].

Finally, if you pass it a warning class, it will check that the specific class of warning was raised and no other.

    >>> with assert_produces_warning(UserWarning):
    ...     warnings.warn(RuntimeWarning())
    Traceback (most recent call last):
        ...
    AssertionError: Did not see expected warning of class 'UserWarning'.