use pytest-mock to simplify and improve tests, improve test docs

appveyor.yml

@@ -28,7 +28,7 @@ install:
     - cmd: conda info -a
 
     # install depenencies
-    - cmd: conda create -n test_env --yes --quiet python=%PYTHON_VERSION% pip numpy scipy pytables pandas nose pytest pytz ephem numba siphon -c conda-forge
+    - cmd: conda create -n test_env --yes --quiet python=%PYTHON_VERSION% pip numpy scipy pytables pandas nose pytest pytz ephem numba siphon pytest-mock -c conda-forge
     - cmd: activate test_env
     - cmd: python --version
     - cmd: conda list

ci/requirements-py27-min.yml

@@ -4,6 +4,7 @@ dependencies:
     - pytz
     - pytest
     - pytest-cov
+    - pytest-mock
     - nose
     - pip:
         - coveralls

ci/requirements-py27.yml

@@ -14,6 +14,7 @@ dependencies:
     - siphon
     - pytest
     - pytest-cov
+    - pytest-mock
     - nose
     - pip:
         - coveralls

ci/requirements-py34.yml

@@ -14,6 +14,7 @@ dependencies:
     - siphon
     - pytest
     - pytest-cov
+    - pytest-mock
     - nose
     - pip:
         - coveralls

ci/requirements-py35.yml

@@ -14,6 +14,7 @@ dependencies:
     - siphon
     - pytest
     - pytest-cov
+    - pytest-mock
     - nose
     - pip:
         - coveralls

ci/requirements-py36.yml

@@ -14,6 +14,7 @@ dependencies:
     #- siphon
     - pytest
     - pytest-cov
+    - pytest-mock
     - nose
     - pip:
         - coveralls

docs/sphinx/source/contributing.rst

@@ -9,7 +9,7 @@ contribute.
 
 
 Easy ways to contribute
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Here are a few ideas for you can contribute, even if you are new to
 pvlib-python, git, or Python:
@@ -33,7 +33,7 @@ pvlib-python, git, or Python:
 
 
 How to contribute new code
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contributors to pvlib-python use GitHub's pull requests to add/modify
 its source code. The GitHub pull request process can be intimidating for
@@ -81,29 +81,113 @@ changes, such as fixing documentation typos.
 
 
 Testing
--------
+~~~~~~~
 
 pvlib's unit tests can easily be run by executing ``py.test`` on the
 pvlib directory:
 
-``py.test pvlib``
+``pytest pvlib``
 
 or, for a single module:
 
-``py.test pvlib/test/test_clearsky.py``
+``pytest pvlib/test/test_clearsky.py``
 
-While copy/paste coding should generally be avoided, it's a great way
-to learn how to write unit tests!
+or, for a single test:
 
-Unit test code should be placed in the corresponding test module in the
-pvlib/test directory.
+``pytest pvlib/test/test_clearsky.py::test_ineichen_nans``
+
+Use the ``--pdb`` flag to debug failures and avoid using ``print``.
+
+New unit test code should be placed in the corresponding test module in
+the pvlib/test directory.
 
 Developers **must** include comprehensive tests for any additions or
 modifications to pvlib.
 
+pvlib-python contains 3 "layers" of code: functions, PVSystem/Location,
+and ModelChain. Contributors will need to add tests that correspond to
+the layer that they modify.
+
+Functions
+---------
+Tests of core pvlib functions should ensure that the function returns
+the desired output for a variety of function inputs. The tests should be
+independent of other pvlib functions (see :issue:`394`). The tests
+should ensure that all reasonable combinations of input types (floats,
+nans, arrays, series, scalars, etc) work as expected. Remember that your
+use case is likely not the only way that this function will be used, and
+your input data may not be generic enough to fully test the function.
+Write tests that cover the full range of validity of the algorithm.
+It is also important to write tests that assert the return value of the
+function or that the function throws an exception when input data is
+beyond the range of algorithm validity.
+
+PVSystem/Location
+-----------------
+The PVSystem and Location classes provide convenience wrappers around
+the core pvlib functions. The tests in test_pvsystem.py and
+test_location.py should ensure that the method calls correctly wrap the
+function calls. Many PVSystem/Location methods pass one or more of their
+object's attributes (e.g. PVSystem.module_parameters, Location.latitude)
+to a function. Tests should ensure that attributes are passed correctly.
+These tests should also ensure that the method returns some reasonable
+data, though the precise values of the data should be covered by
+function-specific tests discussed above.
+
+We prefer to use the ``pytest-mock`` framework to write these tests. The
+test below shows an example of testing the ``PVSystem.ashraeiam``
+method. ``mocker`` is a ``pytest-mock`` object. ``mocker.spy`` adds
+features to the ``pvsystem.ashraeiam`` *function* that keep track of how
+it was called. Then a ``PVSystem`` object is created and the
+``PVSystem.ashraeiam`` *method* is called in the usual way. The
+``PVSystem.ashraeiam`` method is supposed to call the
+``pvsystem.ashraeiam`` function with the angles supplied to the method
+call and the value of ``b`` that we defined in ``module_parameters``.
+The ``pvsystem.ashraeiam.assert_called_once_with`` call will test this
+for us! Finally, we check that the output of the method call is
+reasonable.
+
+.. code-block:: python
+    def test_PVSystem_ashraeiam(mocker):
+        # mocker is a pytest-mock object.
+        # mocker.spy adds code to a function to keep track of how its called
+        mocker.spy(pvsystem, 'ashraeiam')
+
+        # set up inputs
+        module_parameters = pd.Series({'b': 0.05})
+        system = pvsystem.PVSystem(module_parameters=module_parameters)
+        thetas = 1
+
+        # call the method
+        iam = system.ashraeiam(thetas)
+
+        # did the method call the function as we expected?
+        # mocker.spy added assert_called_once_with to the function
+        pvsystem.ashraeiam.assert_called_once_with(thetas, b=0.05)
+
+        # check that the output is reasonable, but no need to duplicate
+        # the rigorous tests of the function
+        assert iam < 1.
+
+Avoid writing PVSystem/Location tests that depend sensitively on the
+return value of a statement as a substitute for using mock. These tests
+are sensitive to changes in the functions, which is *not* what we want
+to test here, and are difficult to maintain.
+
+ModelChain
+----------
+The tests in test_modelchain.py should ensure that
+``ModelChain.__init__`` correctly configures the ModelChain object to
+eventually run the selected models. A test should ensure that the
+appropriate method is actually called in the course of
+``Model_chain.run_model``. A test should ensure that the model selection
+does have a reasonable effect on the subsequent calculations, though the
+precise values of the data should be covered by the function tests
+discussed above. ``pytest-mock`` can also be used for testing ``ModelChain``.
+
 
 This documentation
-------------------
+~~~~~~~~~~~~~~~~~~
 
 If this documentation is unclear, help us improve it! Consider looking
 at the `pandas