Documentation and code cleanup in test suite

Add (lots) of documentation for various parts of the test suite in the
form of Python docstrings. Also, clean up some of the redundant code and
fix indentation issues.