commit 568b5cdd71755b3ba12861c72ec918c425b463c3 Author: Arturo Filastò arturo@filasto.net Date: Fri Jan 22 11:03:56 2016 +0100

Add description of what test helpers are in introduction.

* Fix links --- docs/source/writing_test_helpers.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/source/writing_test_helpers.rst b/docs/source/writing_test_helpers.rst index 2206115..d391aa4 100644 --- a/docs/source/writing_test_helpers.rst +++ b/docs/source/writing_test_helpers.rst @@ -1,23 +1,23 @@ Writing Test Helpers ========

-OONI test helpers are... +OONI test helpers are used by OONI nettests to perform their meausrements. They can be used either to establish a ground truth or to exchange information with the probe to determine if some form of network manipulation is happening in the network path between the probe and the backend.

Writing a Censorship Directionality Test Helper --------------------------

Our goal is to write an OONI test helper that helps an OONI-probe client determine the directionality of keyword censorship it has detected. To do this our helper will receive "encoded" data from an OONI-probe client, decode that data into a text string, and send the OONI-probe client a confirmation packet and a second packet containing the decoded string.

-The OONI-backend code-base has many concise examples of test-helpers that you can build off to create your own. For this tutorial I used the `TCP echo test-helper https://github.com/TheTorProject/ooni-backend/blob/479a1bb154037b834292ccc4b3d593d1472b44de/oonib/testhelpers/tcp_helpers.py#L9-L18` as my guide. +The OONI-backend code-base has many concise examples of test-helpers that you can build off to create your own. For this tutorial I used the `TCP echo test-helper https://github.com/TheTorProject/ooni-backend/blob/479a1bb154037b834292ccc4b3d593d1472b44de/oonib/testhelpers/tcp_helpers.py#L9-L18`_ as my guide.

-Following this tutorial requires basic knowledge of event-driven programming (specifically 'Twisted'). You will be more than ready to build and implement a test-helper after reading though one or two `tutorials online. http://krondo.com/?page_id=1327` +Following this tutorial requires basic knowledge of event-driven programming (specifically 'Twisted'). You will be more than ready to build and implement a test-helper after reading though one or two `tutorials online. http://krondo.com/?page_id=1327`_

Creating the test helper --------------

-OONI-backend keeps all the test-helpers in the `oonib/testhelpers directory https://github.com/TheTorProject/ooni-backend/tree/master/oonib/testhelpers` Each individual test helper is a twisted service. Most of the current test-helpers consists of a twisted Factory and a twisted Protocol defined in the test helpers directory and a `stock Twisted Server https://twistedmatrix.com/documents/current/api/twisted.application.internet.html` that is defined in the backend code. We will follow this model in the tutorial. +OONI-backend keeps all the test-helpers in the `oonib/testhelpers directory https://github.com/TheTorProject/ooni-backend/tree/master/oonib/testhelpers`_ Each individual test helper is a twisted service. Most of the current test-helpers consists of a twisted Factory and a twisted Protocol defined in the test helpers directory and a `stock Twisted Server https://twistedmatrix.com/documents/current/api/twisted.application.internet.html`_ that is defined in the backend code. We will follow this model in the tutorial.

-Because of how simple this example test-helper is the job of our test-helper factory is merely to deploy a single instance of our protocol each time it's buildProtocol method is called. Because we have our factory inheret from the base `Factory object https://twistedmatrix.com/trac/browser/tags/releases/twisted-15.5.0/twisted/internet/protocol.py#L27` we merely have to define its ``protocol`` property to point to our protocol.:: +Because of how simple this example test-helper is the job of our test-helper factory is merely to deploy a single instance of our protocol each time it's buildProtocol method is called. Because we have our factory inheret from the base `Factory object https://twistedmatrix.com/trac/browser/tags/releases/twisted-15.5.0/twisted/internet/protocol.py#L27`_ we merely have to define its ``protocol`` property to point to our protocol.::

class TCPDirectionalityTestHelper(Factory): """ @@ -26,7 +26,7 @@ Because of how simple this example test-helper is the job of our test-helper fac protocol = TCPDirectionalityTestProtocol

-The protocol for this helper needs to do two things. First, upon receiving encoded data it needs to send the OONI-probe client back confirmation that the data has been received. Second, it needs to send the decoded data back to the OONI-probe client. Because we are extending the `Protocol object https://twistedmatrix.com/trac/browser/tags/releases/twisted-15.5.0/twisted/internet/protocol.py#L512` we can rewrite its ``dataReceived`` method which is called and passed data whenever it is received.:: +The protocol for this helper needs to do two things. First, upon receiving encoded data it needs to send the OONI-probe client back confirmation that the data has been received. Second, it needs to send the decoded data back to the OONI-probe client. Because we are extending the `Protocol object https://twistedmatrix.com/trac/browser/tags/releases/twisted-15.5.0/twisted/internet/protocol.py#L512`_ we can rewrite its ``dataReceived`` method which is called and passed data whenever it is received.::

class TCPDirectionalityTestProtocol(Protocol): @@ -68,7 +68,7 @@ With this added we have completed the base of simple test-helper and now just ha Adding the helper to the config file ------

-OONI-backend uses a config file located at `/etc/oonibackend.conf https://github.com/TheTorProject/ooni-backend/blob/master/oonib.conf.example`. This file contains a `section where each test-helper can be configured. https://github.com/TheTorProject/ooni-backend/blob/479a1bb154037b834292ccc4b3d593d1472b44de/oonib.conf.example#L33-L65`. +OONI-backend uses a config file located at `/etc/oonibackend.conf https://github.com/TheTorProject/ooni-backend/blob/master/oonib.conf.example`_. This file contains a `section where each test-helper can be configured. https://github.com/TheTorProject/ooni-backend/blob/479a1bb154037b834292ccc4b3d593d1472b44de/oonib.conf.example#L33-L65`_.

The test-helper will need to be given a unique identifyer so that it can be called from the config file. In this example we use ``tcp-directionality`` as our identifyer.

@@ -81,17 +81,17 @@ For a helper to be used in the ooni-backend it needs to be given an identifyer s Adding the helper to the backend ------

-For a helper to be integrated into the ooni-backend it needs to be added to the initialization scripts contained within `oonibackend.py https://github.com/TheTorProject/ooni-backend/blob/master/oonib/oonibackend.py`. +For a helper to be integrated into the ooni-backend it needs to be added to the initialization scripts contained within `oonibackend.py https://github.com/TheTorProject/ooni-backend/blob/master/oonib/oonibackend.py`_.

-The OONI test-helper system is a collection of `Twisted services https://twistedmatrix.com/documents/current/core/howto/application.html`. For our test-helper we will need to define a service that will run our test-helper factory.:: +The OONI test-helper system is a collection of `Twisted services https://twistedmatrix.com/documents/current/core/howto/application.html`_. For our test-helper we will need to define a service that will run our test-helper factory.::

# Create the service that will run our test-helpers factory. tcp_directionality_helper = internet.TCPServer(int(port), tcp_helpers.TCPDirectionalityTestHelper())

-**NOTE:** In this example I have placed the original service in the existing tcp_helpers file. If you created your own file for your test-helper you will have to make sure that you import that file at the top of `oonibackend.py https://github.com/TheTorProject/ooni-backend/blob/master/oonib/oonibackend.py`. +**NOTE:** In this example I have placed the original service in the existing tcp_helpers file. If you created your own file for your test-helper you will have to make sure that you import that file at the top of `oonibackend.py https://github.com/TheTorProject/ooni-backend/blob/master/oonib/oonibackend.py`_.

-OONI uses a `Multi Service https://twistedmatrix.com/documents/current/api/twisted.application.service.MultiService.html` which allows them to combine all the OONI test-helpers and the report-collector into a singlular service for easier management. The next step for creating our test-helper is to add it to the OONI-backend `multiService https://github.com/TheTorProject/ooni-backend/blob/479a1bb154037b834292ccc4b3d593d1472b44de/oonib/oonibackend.py#L33`:: +OONI uses a `Multi Service https://twistedmatrix.com/documents/current/api/twisted.application.service.MultiService.html`_ which allows them to combine all the OONI test-helpers and the report-collector into a singlular service for easier management. The next step for creating our test-helper is to add it to the OONI-backend `multiService https://github.com/TheTorProject/ooni-backend/blob/479a1bb154037b834292ccc4b3d593d1472b44de/oonib/oonibackend.py#L33`_::

# Add the helper as a child of the backends multi-service test-helper multiService.addService(tcp_directionality_helper) @@ -103,7 +103,7 @@ Finally, we need to start our service.::

In order for our test-helper to be managed using the backend config file we will need to modify this code to check the config file for a test-helper that uses the identifyer we selected earlier. For the directionality helper we check to see if our test-helper had its port specified in the config file to determine if it should be run. I also added a default encoding in case

-This snippet contains the final code that would be inserted into `oonibackend.py https://github.com/TheTorProject/ooni-backend/blob/master/oonib/oonibackend.py`.:: +This snippet contains the final code that would be inserted into `oonibackend.py https://github.com/TheTorProject/ooni-backend/blob/master/oonib/oonibackend.py`_.::

# Check to see if our test-helper was defined in the config if config.helpers['tcp-directionality'].port: