You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 6, 2024. It is now read-only.
Copy file name to clipboardexpand all lines: docs/contributing/contributions_api.rst
+28-47
Original file line number
Diff line number
Diff line change
@@ -6,16 +6,16 @@ Contributing to the API
6
6
7
7
This article provides a high level overview of how to contribute changes to the DroneKit-Python source code.
8
8
9
-
.. tip::
9
+
.. tip::
10
10
11
-
We highly recommend that changes and ideas are `discussed with the project team
12
-
<https://github.com/dronekit/dronekit-python/issues>`_ before starting work!
11
+
We highly recommend that changes and ideas are `discussed with the project team
12
+
<https://github.com/dronekit/dronekit-python/issues>`_ before starting work!
13
13
14
14
15
15
Submitting changes
16
16
==================
17
17
18
-
Contributors should fork the main `dronekit/dronekit-python/ <https://github.com/dronekit/dronekit-python>`_
18
+
Contributors should fork the main `dronekit/dronekit-python/ <https://github.com/dronekit/dronekit-python>`_
19
19
repository and contribute changes back to the project master branch using pull requests
20
20
21
21
* Changes should be :ref:`tested locally <contributing-test-code>` before submission.
@@ -32,9 +32,8 @@ Test code
32
32
33
33
There are three test suites in DroneKit-Python:
34
34
35
-
* **Unit tests** (:file:`tests/unit`) — verify all code paths of the API.
35
+
* **Unit tests** (:file:`tests/unit`) — verify all code paths of the API.
36
36
* **Integration tests** (:file:`tests/sitl`) — verify real-world code, examples, and documentation as they would perform in a real environment.
37
-
* **Web client tests** (:file:`tests/web`) — specifically verify the Python library's capability to talk to `DroneKit Cloud <http://cloud.dronekit.io>`_.
38
37
39
38
Test code should be used to verify new and changed functionality. New tests should:
40
39
@@ -46,20 +45,20 @@ Test code should be used to verify new and changed functionality. New tests shou
46
45
Setting up local testing
47
46
------------------------
48
47
49
-
Follow the links below to set up a development environment on your Linux or Windows computer.
48
+
Follow the links below to set up a development environment on your Linux or Windows computer.
50
49
51
50
* :ref:`dronekit_development_linux`
52
51
* :ref:`dronekit_development_windows`
53
52
54
-
The tests require additional pip modules, including `nose <https://nose.readthedocs.org/en/latest/>`_, a
53
+
The tests require additional pip modules, including `nose <https://nose.readthedocs.org/en/latest/>`_, a
55
54
Python library and tool for writing and running test scripts. These can be installed separately using either of the commands below:
56
55
57
56
.. code:: bash
58
57
59
58
# Install just the additional requirements for tests
60
59
pip install requests nose mock
61
60
62
-
# (or) Install all requirements for dronekit, tests, and building documentation
61
+
# (or) Install all requirements for dronekit, tests, and building documentation
63
62
pip install -r requirements.txt
64
63
65
64
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:
@@ -73,35 +72,35 @@ For several tests, you may be required to set an **environment variable**. In yo
73
72
Unit tests
74
73
----------
75
74
76
-
All new features should be created with accompanying unit tests.
75
+
All new features should be created with accompanying unit tests.
77
76
78
77
DroneKit-Python unit tests are based on the `nose <https://nose.readthedocs.org/en/latest/>`_ test framework,
79
-
and use `mock <https://docs.python.org/dev/library/unittest.mock.html>`_ to simulate objects and APIs and
78
+
and use `mock <https://docs.python.org/dev/library/unittest.mock.html>`_ to simulate objects and APIs and
80
79
ensure correct results.
81
80
82
-
To run the tests and display a summary of the results (on any OS),
83
-
navigate to the **dronekit-python** folder and enter the following
81
+
To run the tests and display a summary of the results (on any OS),
82
+
navigate to the **dronekit-python** folder and enter the following
84
83
command on a terminal/prompt:
85
84
86
85
.. code:: bash
87
86
88
87
nosetests dronekit.test.unit
89
-
88
+
90
89
91
90
92
91
93
92
Writing a new unit test
94
93
^^^^^^^^^^^^^^^^^^^^^^^
95
94
96
-
Create any file named :file:`test_XXX.py` in the :file:`tests/unit` folder to add it as a test.
95
+
Create any file named :file:`test_XXX.py` in the :file:`tests/unit` folder to add it as a test.
97
96
Feel free to copy from existing tests to get started. When *nosetests* is run, it will add your new test to its summary.
98
97
99
-
Tests names should be named based on their associated Github issue (for example,
100
-
``test_12.py`` for `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_)
101
-
or describe the functionality covered (for example, ``test_waypoints.py``
98
+
Tests names should be named based on their associated Github issue (for example,
99
+
``test_12.py`` for `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_)
100
+
or describe the functionality covered (for example, ``test_waypoints.py``
102
101
for a unit test for the waypoints API).
103
-
104
-
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``
102
+
103
+
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``
105
104
from the ``notestools`` module:
106
105
107
106
.. note::
@@ -116,7 +115,7 @@ from the ``notestools`` module:
116
115
assert the_number_two >0, '2 should be greater than zero!'
117
116
assert_equals(the_number_two, 2, '2 should equal two!')
118
117
assert_not_equals(the_number_two, 1, '2 should equal one!')
119
-
118
+
120
119
Please add documentation to each test function describing what behavior it verifies.
121
120
122
121
@@ -129,8 +128,8 @@ Integrated tests use a custom test runner that is similar to *nosetests*. On any
129
128
130
129
cd dronekit-python
131
130
nosetests dronekit.test.sitl
132
-
133
-
You can choose to run a specific tests. The example below shows how to run
131
+
132
+
You can choose to run a specific tests. The example below shows how to run
@@ -160,12 +159,12 @@ Integration tests should be written or improved whenever:
160
159
161
160
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.
162
161
163
-
Tests names should be named based on their associated Github issue (for example,
164
-
``test_12.py`` for `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_)
165
-
or describe the functionality covered (for example, ``test_waypoints.py``
162
+
Tests names should be named based on their associated Github issue (for example,
163
+
``test_12.py`` for `issue #12 <https://github.com/dronekit/dronekit-python/issues/12>`_)
164
+
or describe the functionality covered (for example, ``test_waypoints.py``
166
165
for an integration test for the waypoints API).
167
166
168
-
Tests should minimally use the imports shown below and decorate test functions with ``@with_sitl``
167
+
Tests should minimally use the imports shown below and decorate test functions with ``@with_sitl``
169
168
(this sets up the test and passes in a connection string for SITL).
170
169
171
170
.. code:: python
@@ -184,13 +183,13 @@ Tests should minimally use the imports shown below and decorate test functions w
184
183
vehicle.close()
185
184
186
185
187
-
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``
186
+
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``
188
187
from the ``testlib`` module:
189
188
190
189
.. note::
191
190
192
191
Avoiding printing any data from your test!
193
-
192
+
194
193
195
194
196
195
.. code:: python
@@ -202,21 +201,3 @@ from the ``testlib`` module:
202
201
assert_equals(the_number_two, 2, '2 should equal two!'
203
202
204
203
Please add documentation to each test function describing what behavior it verifies.
205
-
206
-
Web client tests
207
-
----------------
208
-
209
-
.. warning::
210
-
211
-
The web client library is being rewritten. Please `discuss with the project team
212
-
<https://github.com/dronekit/dronekit-python/issues>`_ if you intend to develop withorfor the present version of the web client.
213
-
214
-
Web client tests use *nosetests*. To run these, you will need to sign up forAPI keys from`cloud.dronekit.io <https://cloud.dronekit.io/>`_.
215
-
With these, export a variable named ``DRONEAPI_KEY``with a value in the format``<id>.<key>`` to your environment.
216
-
217
-
On anyOS, enter the following command on a terminal/prompt to run the web-client tests (and display summary results):
0 commit comments