From 0302e00ff3d2fe010a47c123794f1df27449abd9 Mon Sep 17 00:00:00 2001 From: Tim Ryan Date: Thu, 16 Jul 2015 17:12:52 -0700 Subject: [PATCH 1/7] Adds CONTRIBUTING.md as a thin link to guides. --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..09b21edbe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing to DroneKit Python + +Please see [the Contribution Guide](http://python.dronekit.io/contributing/) on dronekit.io for details. From 6c2c00dcb793ee2955cacf6ba61d38ddb9b396e8 Mon Sep 17 00:00:00 2001 From: Tim Ryan Date: Thu, 16 Jul 2015 17:23:27 -0700 Subject: [PATCH 2/7] Adds very basic contribution information for tests. --- docs/contributing/contributions_api.rst | 62 +++++++++++++++++++++---- 1 file changed, 52 insertions(+), 10 deletions(-) diff --git a/docs/contributing/contributions_api.rst b/docs/contributing/contributions_api.rst index fbd90e3ee..dcb6766f5 100644 --- a/docs/contributing/contributions_api.rst +++ b/docs/contributing/contributions_api.rst @@ -30,21 +30,63 @@ 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. Changes to DroneKit can be tested locally by -rebuilding your git branch and running it against SITL. The links below provide information on how -to set up a development environment on your development computer: +Test code should be used to verify new and changed functionality. Changes to DroneKit can be tested locally by rebuilding your git branch and running it locally. The links below provide information on how to set up a development environment on your development computer: * :ref:`dronekit_development_linux` * :ref:`dronekit_development_windows` -.. note:: At time of writing (June 2015) we do not yet have formal acceptance tests (unit tests, system tests). +Running Web Client Tests +======================== -We recommend that you provide your test script as a gist, and run any the -:ref:`DroneKit-Python Examples ` that are relevant. - -For example, the addition of a new API item for retrieving a vehicle attribute would need test code for -getting, setting (if applicable) and printing the attribute. An easy way to create this would be to -update and run :ref:`example-vehicle-state`. +Web client tests use nose. First export a DRONEAPI_KEY in the format `.`. The run: +.. code:: bash + cd dronekit-python + nosetests tests/web +Running Integrated Tests +======================== + +Integrated tests use the SITL environment to run DroneKit tests against a simulated copter. + + +.. code:: bash + + cd dronekit-python/tests + python -um sitl + +You can configure any of these environment variables to update it: + +#. TEST_SPEEDUP - Speedup factor to SITL. +#. TEST_RATE - Sets framerate. (Default is 200 for copter, 50 for rover, 200 for plane.) +#. TEST_RETRY - Retry failed tests. This is useful if your testing environment performs inconsistently with the simulated copter. + +You can also specify specific test names using: + +.. code:: bash + + python -um sitl test_1.py test2_.py ... + +Writing a new Test + +You can write a new integrated test by adding a file with the naming scheme `test_XXX.py` to the `sitl` directory. In this file, functions with the prefix `test_` will be called with the `local_connect` parameter. For example: + +.. code:: python + + from testlib import assert_equals + + def test_parameters(local_connect): + v = local_connect().get_vehicles()[0] + + # Simple parameter checks + assert_equals(type(v.parameters['THR_MIN']), float) + +This checks to see that the parameter object is of type float. Use assertions to test your code is consistent. Avoiding printing any data from your test. + +The whole API is accessible from test files. Running `python -um sitl` will collect and run any new tests when invoked. + +Running Unit Tests +================== + +There are none, tim get on that. From 973fcae4bad52d996abc13aae492dd5b37067226 Mon Sep 17 00:00:00 2001 From: Tim Ryan Date: Wed, 22 Jul 2015 13:04:27 -0700 Subject: [PATCH 3/7] Updates contribution docs with unit tests. --- docs/contributing/contributions_api.rst | 94 ++++++++++++++++++------- 1 file changed, 68 insertions(+), 26 deletions(-) diff --git a/docs/contributing/contributions_api.rst b/docs/contributing/contributions_api.rst index dcb6766f5..0979aefb4 100644 --- a/docs/contributing/contributions_api.rst +++ b/docs/contributing/contributions_api.rst @@ -30,63 +30,105 @@ 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. Changes to DroneKit can be tested locally by rebuilding your git branch and running it locally. The links below provide information on how to set up a development environment on your development computer: +Test code should be used to verify new and changed functionality. 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. * :ref:`dronekit_development_linux` * :ref:`dronekit_development_windows` -Running Web Client Tests -======================== +-------------- +Test Structure +-------------- -Web client tests use nose. First export a DRONEAPI_KEY in the format `.`. The run: +There are three test suites in DroneKit Python. + +* ``tests/unit`` — **Unit tests** verify all code paths of the API. +* ``tests/sitl`` — **Integration tests** verify real-world code, examples, and documentation as they would perform in a real environment. +* ``tests/web`` — **Web client** tests specifically verify the Python library's capability to talk to `DroneKit Cloud `_. + +Several of these test suites use `nose `_, 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 requirements.txt). + +Unit Tests +^^^^^^^^^^^ + +Unit tests use ``nosetests``. On any OS, type this in the command line to run, then see a summary of, all unit tests: .. code:: bash cd dronekit-python - nosetests tests/web + nosetests tests/unit -Running Integrated Tests -======================== +For unit tests, `mock `_ is used to simulate objects and APIs and ensure correct results. -Integrated tests use the SITL environment to run DroneKit tests against a simulated copter. +Writing a new Test +"""""""""""""""""" +Good unit tests should: + +#. Accompany all new features that are written. +#. Verify all code paths that code can take. +#. Be concise and straightforward. + +Create any file named `test_XXX.py` in the 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. + +Integrated Tests +^^^^^^^^^^^^^^^^ + +Integrated tests use a custom test runner that is similar to ``nosetests``. On any OS, type this in the command line to run, then see a summary of, all integrated tests: .. code:: bash - cd dronekit-python/tests - python -um sitl + cd dronekit-python + python -um tests.sitl -You can configure any of these environment variables to update it: +Integrated tests use the SITL environment to run DroneKit tests against a simulated copter. Because these tests emulate a copter in real-time, you can set several environment variables to tweak the environment code is run in: -#. TEST_SPEEDUP - Speedup factor to SITL. -#. TEST_RATE - Sets framerate. (Default is 200 for copter, 50 for rover, 200 for plane.) -#. TEST_RETRY - Retry failed tests. This is useful if your testing environment performs inconsistently with the simulated copter. +#. ``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 also specify specific test names using: +You can choose to test specific files by passing them as arguments: .. code:: bash - python -um sitl test_1.py test2_.py ... + python -um tests.sitl test_1.py test2_.py ... Writing a new Test +"""""""""""""""""" -You can write a new integrated test by adding a file with the naming scheme `test_XXX.py` to the `sitl` directory. In this file, functions with the prefix `test_` will be called with the `local_connect` parameter. For example: +Integration tests should be written or improved whenever: + +#. New functionality has been added to encapsulate or abstract older methods of interacting with the API. +#. 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 ``test_XXX.py`` to the ``tests/sitl`` directory. In this file, functions with the prefix ``test_`` will be called with the `local_connect` parameter. For example: .. code:: python - from testlib import assert_equals + from testlib import assert_equals - def test_parameters(local_connect): - v = local_connect().get_vehicles()[0] + def test_parameters(local_connect): + v = local_connect().get_vehicles()[0] - # Simple parameter checks - assert_equals(type(v.parameters['THR_MIN']), float) + # Simple parameter checks + assert_equals(type(v.parameters['THR_MIN']), float) This checks to see that the parameter object is of type float. Use assertions to test your code is consistent. Avoiding printing any data from your test. -The whole API is accessible from test files. Running `python -um sitl` will collect and run any new tests when invoked. +Web Client Tests +^^^^^^^^^^^^^^^^ -Running Unit Tests -================== +Web client tests use ``nosetests``. To run these, you will need to sign up for API keys from `cloud.dronekit.io `_. With these, you can export to your enviroment a variable called DRONEAPI_KEY in the format `.`: + +.. code:: bash + + export DRONEAPI_KEY=. # works on OS X and Linux + set DRONEAPI_KEY=. # works on Windows cmd.exe + $env:DRONEAPI_KEY="." # works on Windows Powershell -There are none, tim get on that. +On any OS, type this in the command line to run, then see a summary of, all unit tests: + +.. code:: bash + + cd dronekit-python + nosetests tests/web From b253ead4e8b3b19edd1809416e1cfb8375534418 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Thu, 23 Jul 2015 09:57:43 +1000 Subject: [PATCH 4/7] Minor restructure, subedit, fix markup --- docs/contributing/contributions_api.rst | 63 +++++++++++++------------ 1 file changed, 34 insertions(+), 29 deletions(-) diff --git a/docs/contributing/contributions_api.rst b/docs/contributing/contributions_api.rst index 0979aefb4..42a4290c1 100644 --- a/docs/contributing/contributions_api.rst +++ b/docs/contributing/contributions_api.rst @@ -30,27 +30,27 @@ 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. 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. +Test code should be used to verify new and changed functionality. There are three test suites in DroneKit-Python: -* :ref:`dronekit_development_linux` -* :ref:`dronekit_development_windows` +* **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 `_. + +Setting up local testing +------------------------ --------------- -Test Structure --------------- +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. -There are three test suites in DroneKit Python. +* :ref:`dronekit_development_linux` +* :ref:`dronekit_development_windows` -* ``tests/unit`` — **Unit tests** verify all code paths of the API. -* ``tests/sitl`` — **Integration tests** verify real-world code, examples, and documentation as they would perform in a real environment. -* ``tests/web`` — **Web client** tests specifically verify the Python library's capability to talk to `DroneKit Cloud `_. +Several of the test suites use `nose `_, 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`). -Several of these test suites use `nose `_, 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 requirements.txt). -Unit Tests -^^^^^^^^^^^ +Unit tests +---------- -Unit tests use ``nosetests``. On any OS, type this in the command line to run, then see a summary of, all 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): .. code:: bash @@ -59,8 +59,9 @@ Unit tests use ``nosetests``. On any OS, type this in the command line to run, t For unit tests, `mock `_ is used to simulate objects and APIs and ensure correct results. -Writing a new Test -"""""""""""""""""" + +Writing a new unit test +^^^^^^^^^^^^^^^^^^^^^^^ Good unit tests should: @@ -68,19 +69,21 @@ Good unit tests should: #. Verify all code paths that code can take. #. Be concise and straightforward. -Create any file named `test_XXX.py` in the 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. +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. + -Integrated Tests -^^^^^^^^^^^^^^^^ -Integrated tests use a custom test runner that is similar to ``nosetests``. On any OS, type this in the command line to run, then see a summary of, all integrated tests: +Integration tests +----------------- + +Integrated tests use a custom test runner that is similar to *nosetests*. On any OS, enter the following command on a terminal/prompt to run all the integrated tests (and display summary results): .. code:: bash cd dronekit-python python -um tests.sitl -Integrated tests use the SITL environment to run DroneKit tests against a simulated copter. Because these tests emulate a copter in real-time, you can set several environment variables to tweak the environment code is run in: +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. @@ -92,8 +95,8 @@ You can choose to test specific files by passing them as arguments: python -um tests.sitl test_1.py test2_.py ... -Writing a new Test -"""""""""""""""""" +Writing a new integration test +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Integration tests should be written or improved whenever: @@ -101,7 +104,7 @@ 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 ``test_XXX.py`` to the ``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 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: .. code:: python @@ -113,12 +116,14 @@ You can write a new integrated test by adding a file with the naming scheme ``te # Simple parameter checks assert_equals(type(v.parameters['THR_MIN']), float) -This checks to see that the parameter object is of type float. Use assertions to test your code is consistent. Avoiding printing any data from your test. +This checks to see that the parameter object is of type `float`. Use assertions to test your code is consistent. Avoiding printing any data from your test. + -Web Client Tests -^^^^^^^^^^^^^^^^ +Web-Client tests +---------------- -Web client tests use ``nosetests``. To run these, you will need to sign up for API keys from `cloud.dronekit.io `_. With these, you can export to your enviroment a variable called DRONEAPI_KEY in the format `.`: +Web client tests use *nosetests*. To run these, you will need to sign up for API keys from `cloud.dronekit.io `_. +With these, you can export a variable called ``DRONEAPI_KEY`` (with the format ``.``) to your environment: .. code:: bash @@ -126,7 +131,7 @@ Web client tests use ``nosetests``. To run these, you will need to sign up for A set DRONEAPI_KEY=. # works on Windows cmd.exe $env:DRONEAPI_KEY="." # works on Windows Powershell -On any OS, type this in the command line to run, then see a summary of, all unit tests: +On any OS, enter the following command on a terminal/prompt to run the web-client tests (and display summary results): .. code:: bash From 05645e284610c6d73c17576dab054e51ee0fa3d7 Mon Sep 17 00:00:00 2001 From: Tim Ryan Date: Thu, 23 Jul 2015 14:20:16 -0700 Subject: [PATCH 5/7] Updates to address Hamish feedback. --- docs/contributing/contributions_api.rst | 47 ++++++++++++++++++++----- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/docs/contributing/contributions_api.rst b/docs/contributing/contributions_api.rst index 42a4290c1..39cf76700 100644 --- a/docs/contributing/contributions_api.rst +++ b/docs/contributing/contributions_api.rst @@ -46,6 +46,13 @@ The links below provide information on how to set up a development environment o Several of the test suites use `nose `_, 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`). +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: + +.. code:: bash + + export NAME=VALUE # works on OS X and Linux + set NAME=VALUE # works on Windows cmd.exe + $env:NAME = "VALUE" # works on Windows Powershell Unit tests ---------- @@ -71,7 +78,19 @@ 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. +Tests names should refer directly to a Github issue (for example, ``test_12.py`` would refer to `issue #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: + +.. code:: python + + from nose.tools import assert_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!' + +Please add documentation to each test function describing what behavior it verifies. Integration tests ----------------- @@ -116,20 +135,32 @@ You can write a new integrated test by adding a file with the naming scheme :fil # Simple parameter checks assert_equals(type(v.parameters['THR_MIN']), float) -This checks to see that the parameter object is of type `float`. Use assertions to test your code is consistent. Avoiding printing any data from your test. +This checks to see that the parameter object is of type `float`. + +Tests names should refer directly to a Github issue (for example, ``test_12.py`` would refer to `issue #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 ``testlib`` module: -Web-Client tests +.. code:: python + + from testlib import assert_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!' + +Please add documentation to each test function describing what behavior it verifies. + +Web client tests ---------------- -Web client tests use *nosetests*. To run these, you will need to sign up for API keys from `cloud.dronekit.io `_. -With these, you can export a variable called ``DRONEAPI_KEY`` (with the format ``.``) to your environment: +.. warning:: -.. code:: bash + The web client library is being rewritten. Please `discuss with the project team + `_ if you intend to develop with or for the present version of the web client. - export DRONEAPI_KEY=. # works on OS X and Linux - set DRONEAPI_KEY=. # works on Windows cmd.exe - $env:DRONEAPI_KEY="." # works on Windows Powershell +Web client tests use *nosetests*. To run these, you will need to sign up for API keys from `cloud.dronekit.io `_. +With these, export a variable named ``DRONEAPI_KEY`` with a value in the format ``.`` to your environment. On any OS, enter the following command on a terminal/prompt to run the web-client tests (and display summary results): From 63e93583318e1234c849c55632b41362c6a15d9d Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 24 Jul 2015 11:14:35 +1000 Subject: [PATCH 6/7] Update contributions_api.rst --- docs/contributing/contributions_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/contributions_api.rst b/docs/contributing/contributions_api.rst index 39cf76700..cfd1bb0d4 100644 --- a/docs/contributing/contributions_api.rst +++ b/docs/contributing/contributions_api.rst @@ -80,7 +80,7 @@ Create any file named :file:`test_XXX.py` in the :file:`tests/unit` folder to ad Tests names should refer directly to a Github issue (for example, ``test_12.py`` would refer to `issue #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. 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: .. code:: python From 1ab7d827e7e66e1e51b55073d4831dc5311817c4 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 24 Jul 2015 11:17:29 +1000 Subject: [PATCH 7/7] Update contributions_api.rst Fix another minor typo --- docs/contributing/contributions_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/contributions_api.rst b/docs/contributing/contributions_api.rst index cfd1bb0d4..c3bdfbc14 100644 --- a/docs/contributing/contributions_api.rst +++ b/docs/contributing/contributions_api.rst @@ -139,7 +139,7 @@ This checks to see that the parameter object is of type `float`. Tests names should refer directly to a Github issue (for example, ``test_12.py`` would refer to `issue #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 ``testlib`` module: +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