testing_practices.rst

Running tests

The run_tests.py script provided here will run all tests in the tests directory and in docstrings and report coverage. This script is simply a wrapper around the pytest command.

Alternatively doctests can be invoked specivially via xdoctest -m watch to run all doctests, or xdoctest -m <path-to-file> to run all doctests in a file.

Writing tests

GeoWATCH uses the pytest module for running unit tests. Unit tests should be added into the tests directory and files should be prefixed with test_.

Additionally, code blocks in function docstrings will be interpreted as tests using xdoctest as part of the Google docstring convention.

For example here are what doctests look like for a class and for a function:

class GdalOpen:
    """
    A simple context manager for friendlier gdal use.

    Example:
        >>> # xdoctest: +REQUIRES(--network)
        >>> from watch.utils.util_raster import *
        >>> from watch.demo.landsat_demodata import grab_landsat_product
        >>> path = grab_landsat_product()['bands'][0]
        >>>
        >>> # standard use:
        >>> dataset = gdal.Open(path)
        >>> print(dataset.GetDescription())  # do stuff
        >>> del dataset  # or 'dataset = None'
        >>>
        >>> # equivalent:
        >>> with GdalOpen(path) as dataset:
        >>>     print(dataset.GetDescription())  # do stuff
    """
    # code goes here

def my_cool_function(inputs):
    """
    The purpose of this function is to demonstrate how to write a doctest.

    Example:
        >>> # An example of how to use my cool function
        >>> # The xdoctest module will run this as a test
        >>> inputs = 'construct-demo-data'
        >>> my_cool_function(inputs)
    """
    import this
    print('You input: {}'.format(inputs))