commit c2e0def0fbac26f8262b6304d5aa692392612360
Author: Arturo Filastò <[email protected]>
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:
_______________________________________________
tor-commits mailing list
[email protected]
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits
