Merge pull request dronekit#495 from dronekit/hgw_test_update_dkpy2

Update test instructions to dkpy2

Author: mrpollo

docs/contributing/contributions_api.rst

@@ -30,21 +30,37 @@ repository and contribute changes back to the project master branch using pull r
 Test code
 =========
 
-Test code should be used to verify new and changed functionality. There are three test suites in DroneKit-Python:
+There are three test suites in DroneKit-Python:
 
 * **Unit tests** (:file:`tests/unit`) — verify all code paths of the API. 
 * **Integration tests** (:file:`tests/sitl`) — verify real-world code, examples, and documentation as they would perform in a real environment.
 * **Web client tests** (:file:`tests/web`) — specifically verify the Python library's capability to talk to `DroneKit Cloud <http://cloud.dronekit.io>`_.
 
+Test code should be used to verify new and changed functionality. New tests should:
+
+#. Verify all code paths that code can take.
+#. Be concise and straightforward.
+#. Be documented.
+
+
 Setting up local testing
 ------------------------
 
-The links below provide information on how to set up a development environment on your development computer. Changes to DroneKit can then be tested locally. 
+Follow the links below to set up a development environment on your Linux or Windows computer. 
 
 * :ref:`dronekit_development_linux`
 * :ref:`dronekit_development_windows`
 
-Several of the test suites use `nose <https://nose.readthedocs.org/en/latest/>`_, a Python library for writing test scripts and a command line tool for running these. When setting up your dev environment, all test dependencies will have been installed (via :file:`requirements.txt`).
+The tests require additional pip modules, including `nose <https://nose.readthedocs.org/en/latest/>`_, a 
+Python library and tool for writing and running test scripts. These can be installed separately using either of the commands below:
+
+.. code:: bash
+
+    # Install just the additional requirements for tests
+    pip install requests nose mock
+
+    # (or) Install all requirements for dronekit, tests, and building documentation   
+    pip install -r requirements.txt
 
 For several tests, you may be required to set an **environment variable**. In your command line, you can set the name of a variable to equal a value using the following invocation, depending on your OS:
 
@@ -57,41 +73,53 @@ For several tests, you may be required to set an **environment variable**. In yo
 Unit tests
 ----------
 
-Unit tests use *nosetests*. On any OS, enter the following command on a terminal/prompt to run the unit tests (and display a summary of the results):
+All new features should be created with accompanying unit tests. 
+
+DroneKit-Python unit tests are based on the `nose <https://nose.readthedocs.org/en/latest/>`_ test framework,
+and use `mock <https://docs.python.org/dev/library/unittest.mock.html>`_ to simulate objects and APIs and 
+ensure correct results.
+
+To run the tests and display a summary of the results (on any OS), 
+navigate to the **dronekit-python** folder and enter the following 
+command on a terminal/prompt:
 
 .. code:: bash
 
-    cd dronekit-python
-    nosetests tests/unit
+    nosetests dronekit.test.unit
+ 
 
-For unit tests, `mock <https://docs.python.org/dev/library/unittest.mock.html>`_ is used to simulate objects and APIs and ensure correct results.
 
 
 Writing a new unit test
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Good unit tests should:
+Create any file named :file:`test_XXX.py` in the :file:`tests/unit` folder to add it as a test. 
+Feel free to copy from existing tests to get started. When *nosetests* is run, it will add your new test to its summary.
 
-#. Accompany all new features that are written.
-#. Verify all code paths that code can take.
-#. Be concise and straightforward.
+Tests names should be named based on their associated Github issue (for example, 
+``test_12.py`` for `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_) 
+or describe the functionality covered (for example, ``test_waypoints.py`` 
+for a unit test for the waypoints API).
+  
+Use assertions to test your code is consistent. You can use the built-in Python ``assert`` macro as well as ``assert_equals`` and ``assert_not_equals`` 
+from the ``notestools`` module:
 
-Create any file named :file:`test_XXX.py` in the :file:`tests/unit` folder to add it as a test. Feel free to copy from existing tests to get started. When *nosetests* is run, it will add your new test to its summary.
+.. note::
 
-Tests names should refer directly to a Github issue (for example, ``test_12.py`` would refer to `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_ or describe fully what functionality they encompass (for example, ``test_waypoints.py`` would describe a unit test for the waypoints API).
-
-Avoiding printing any data from your test. Instead, use assertions to test your code is consistent. You can use the built-in Python ``assert`` macro as well as ``assert_equals`` from the ``nose.tools`` module:
+    Avoiding printing any data from your test!
 
 .. code:: python
 
-    from nose.tools import assert_equals
+    from nose.tools import assert_equals, assert_not_equals
 
     def test_this(the_number_two):
         assert the_number_two > 0, '2 should be greater than zero!'
-        assert_equals(the_number_two, 2, '2 should equal two!'
-
+        assert_equals(the_number_two, 2, '2 should equal two!')
+        assert_not_equals(the_number_two, 1, '2 should equal one!')
+        
 Please add documentation to each test function describing what behavior it verifies.
 
+
 Integration tests
 -----------------
 
@@ -100,19 +128,26 @@ Integrated tests use a custom test runner that is similar to *nosetests*. On any
 .. code:: bash
 
     cd dronekit-python
-    python -um tests.sitl
+    nosetests dronekit.test.sitl
+    
+You can choose to run a specific tests. The example below shows how to run 
+**\dronekit-python\dronekit\test\sitl\test_12.py**.
+
+.. code:: bash
+
+    nosetests dronekit.test.sitl.test_12
+
+
+Configuring the test environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Integrated tests use the SITL environment to run DroneKit tests against a simulated Copter. Because these tests emulate Copter in real-time, you can set several environment variables to tweak the environment that code is run in:
 
 #. ``TEST_SPEEDUP`` - Speedup factor to SITL. Default is ``TEST_SPEEDUP=1``. You can increase this factor to speed up how long your tests take to run.
 #. ``TEST_RATE`` - Sets framerate. Default is ``TEST_RATE=200`` for copter, 50 for rover, 50 for plane.
 #. ``TEST_RETRY`` - Retry failed tests. Default is ``TEST_RETRY=1``. This is useful if your testing environment generates inconsistent success rates because of timing.
 
-You can choose to test specific files by passing them as arguments:
 
-.. code:: bash
-
-    python -um tests.sitl test_1.py test2_.py ...
 
 Writing a new integration test
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -123,23 +158,40 @@ Integration tests should be written or improved whenever:
 #. Example code or documentation has been added.
 #. A feature could not be tested by unit tests alone (e.g. timing issues, mode changing, etc.)
 
-You can write a new integrated test by adding a file with the naming scheme :file:`test_XXX.py` to the :file:`tests/sitl` directory. In this file, functions with the prefix ``test_`` will be called with the ``local_connect`` parameter. For example:
+You can write a new integrated test by adding (or copying) a file with the naming scheme :file:`test_XXX.py` to the :file:`tests/sitl` directory.
+
+Tests names should be named based on their associated Github issue (for example, 
+``test_12.py`` for `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_) 
+or describe the functionality covered (for example, ``test_waypoints.py`` 
+for an integration test for the waypoints API).
+
+Tests should minimally use the imports shown below and decorate test functions with ``@with_sitl`` 
+(this sets up the test and passes in a connection string for SITL).
 
 .. code:: python
 
-    from testlib import assert_equals
+    from dronekit import connect
+    from dronekit.test import with_sitl
+    from nose.tools import assert_equals, assert_not_equals
+
+    @with_sitl
+    def test_something(connpath):
+        vehicle = connect(connpath)
+
+        # Test using assert, assert_equals and assert_not_equals
+        ...
+
+        vehicle.close()
 
-    def test_parameters(local_connect):
-        v = local_connect().get_vehicles()[0]
 
-        # Simple parameter checks
-        assert_equals(type(v.parameters['THR_MIN']), float)
+Use assertions to test your code is consistent. You can use the built-in Python ``assert`` macro as well as ``assert_equals`` and ``assert_not_equals`` 
+from the ``testlib`` module:
 
-This checks to see that the parameter object is of type `float`.
+.. note::
 
-Tests names should refer directly to a Github issue (for example, ``test_12.py`` would refer to `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_ or describe fully what functionality they encompass (for example, ``test_waypoints.py`` would describe a unit test for the waypoints API).
+    Avoiding printing any data from your test!
+    
 
-Avoiding printing any data from your test. Instead, use assertions to test your code is consistent. You can use the built-in Python ``assert`` macro as well as ``assert_equals`` from the ``testlib`` module:
 
 .. code:: python