[tor-commits] [stem/master] Converting test.* contents to reStructuredText
atagar at torproject.org
atagar at torproject.org
Sun Jun 10 22:19:04 UTC 2012
commit 65351e9eea2a30e81632e045c0b2825d0573719c
Author: Damian Johnson <atagar at torproject.org>
Date: Sun Jun 10 15:16:57 2012 -0700
Converting test.* contents to reStructuredText
The test contents aren't currently included in the stem documentation, since
they aren't generally of interest to users. However, might as well do its
documentation as reStructuredText for consistency's sake.
I'll probably include just the framework utilities with our documenntation
later to help people hacking on stem.
---
test/check_whitespace.py | 13 +--
test/integ/connection/authentication.py | 26 +---
test/mocking.py | 76 +++++------
test/output.py | 11 +-
test/runner.py | 184 ++++++++++---------------
test/unit/control/__init__.py | 6 -
test/unit/descriptor/extrainfo_descriptor.py | 8 +-
test/unit/descriptor/server_descriptor.py | 10 +-
8 files changed, 132 insertions(+), 202 deletions(-)
diff --git a/test/check_whitespace.py b/test/check_whitespace.py
index e0419a5..db97130 100644
--- a/test/check_whitespace.py
+++ b/test/check_whitespace.py
@@ -18,12 +18,9 @@ def get_issues(base_path = DEFAULT_TARGET):
"""
Checks python source code in the given directory for whitespace issues.
- Arguments:
- base_path (str) - directory to be iterated over
+ :param str base_path: directory to be iterated over
- Returns:
- dict of the form...
- path => [(line_number, message)...]
+ :returns: dict of the form ``path => [(line_number, message)...]``
"""
# TODO: This does not check that block indentations are two spaces because
@@ -80,11 +77,9 @@ def _get_python_files(base_path):
"""
Iterates over all of the python files within a directory.
- Arguments:
- base_path (str) - directory to be iterated over
+ :param str base_path: directory to be iterated over
- Returns:
- iterator that yields the absolute path for python source code
+ :returns: iterator that yields the absolute path for python source code
"""
for root, _, files in os.walk(base_path, followlinks = True):
diff --git a/test/integ/connection/authentication.py b/test/integ/connection/authentication.py
index ee7bb32..4f1d504 100644
--- a/test/integ/connection/authentication.py
+++ b/test/integ/connection/authentication.py
@@ -32,11 +32,9 @@ def _can_authenticate(auth_type):
Checks if a given authentication method can authenticate to our control
socket.
- Arguments:
- auth_type (stem.connection.AuthMethod) - authentication method to check
+ :param stem.connection.AuthMethod auth_type: authentication method to check
- Returns:
- bool that's True if we should be able to authenticate and False otherwise
+ :returns: bool that's True if we should be able to authenticate and False otherwise
"""
runner = test.runner.get_runner()
@@ -59,11 +57,9 @@ def _get_auth_failure_message(auth_type):
authentication fails. Note that this test will need to be updated if tor
changes its rejection reponse.
- Arguments:
- auth_type (stem.connection.AuthMethod) - authentication method to check
+ :param stem.connection.AuthMethod auth_type: authentication method to check
- Returns:
- string with the rejection message that tor would provide
+ :returns: string with the rejection message that tor would provide
"""
tor_options = test.runner.get_runner().get_options()
@@ -200,9 +196,6 @@ class TestAuthenticate(unittest.TestCase):
individually.
"""
-
-
-
runner = test.runner.get_runner()
tor_options = runner.get_options()
is_cookie_only = test.runner.Torrc.COOKIE in tor_options and not test.runner.Torrc.PASSWORD in tor_options
@@ -349,14 +342,11 @@ class TestAuthenticate(unittest.TestCase):
not then we check that this gives a message that we'd expect then raises
the exception.
- Arguments:
- auth_type (stem.connection.AuthMethod) - method by which we should
- authentiate to the control socket
- auth_arg (str) - argument to be passed to the authentication function
- check_message (bool) - checks that failure messages are what we'd expect
+ :param stem.connection.AuthMethod auth_type: method by which we should authentiate to the control socket
+ :param str auth_arg: argument to be passed to the authentication function
+ :param bool check_message: checks that failure messages are what we'd expect
- Raises:
- stem.connection.AuthenticationFailure if the authentication fails
+ :raises: :class:`stem.connection.AuthenticationFailure` if the authentication fails
"""
with test.runner.get_runner().get_tor_socket(False) as control_socket:
diff --git a/test/mocking.py b/test/mocking.py
index f17dcc9..290393e 100644
--- a/test/mocking.py
+++ b/test/mocking.py
@@ -2,23 +2,25 @@
Helper functions for creating mock objects and monkey patching to help with
testing. With python's builtin unit testing framework the setUp and test
functions set up mocking, which is then reverted in the tearDown method by
-calling 'revert_mocking'.
-
-mock - replaces a function with an alternative implementation
-revert_mocking - reverts any changes made by the mock function
-get_real_function - provides the non-mocked version of a function
-
-Mocking Functions
- no_op - does nothing
- return_value - returns a given value
- return_true - returns True
- return_false - returns False
- return_none - returns None
- raise_exception - raises an exception when called
-
-Instance Constructors
- get_message - stem.socket.ControlMessage
- get_protocolinfo_response - stem.response.protocolinfo.ProtocolInfoResponse
+calling :func:`test.mocking.revert_mocking`.
+
+::
+
+ mock - replaces a function with an alternative implementation
+ revert_mocking - reverts any changes made by the mock function
+ get_real_function - provides the non-mocked version of a function
+
+ Mocking Functions
+ no_op - does nothing
+ return_value - returns a given value
+ return_true - returns True
+ return_false - returns False
+ return_none - returns None
+ raise_exception - raises an exception when called
+
+ Instance Constructors
+ get_message - stem.socket.ControlMessage
+ get_protocolinfo_response - stem.response.protocolinfo.ProtocolInfoResponse
"""
import inspect
@@ -63,8 +65,7 @@ def support_with(obj):
methods to the object. The __enter__ provides the object itself and __exit__
does nothing.
- Arguments:
- obj (object) - object to support the 'with' keyword
+ :param object obj: object to support the 'with' keyword
"""
obj.__dict__["__enter__"] = return_value(obj)
@@ -75,9 +76,8 @@ def mock(target, mock_call):
Mocks the given function, saving the initial implementation so it can be
reverted later.
- Arguments:
- target (function) - function to be mocked
- mock_call (functor) - mocking to replace the function with
+ :param function target: function to be mocked
+ :param functor mock_call: mocking to replace the function with
"""
# Builtin functions need special care because the builtin_function_or_method
@@ -120,10 +120,9 @@ def mock_method(target_class, method_name, mock_call):
Mocks the given class method in a similar fasion as what mock() does for
functions.
- Arguments:
- target_class (class) - class with the method we want to mock
- method_name (str) - name of the method to be mocked
- mock_call (functor) - mocking to replace the method with
+ :param class target_class: class with the method we want to mock
+ :param str method_name: name of the method to be mocked
+ :param functor mock_call: mocking to replace the method with
"""
# Ideally callers could call us with just the method, for instance like...
@@ -179,11 +178,9 @@ def get_real_function(function):
Provides the original, non-mocked implementation for a function or method.
This simply returns the current implementation if it isn't being mocked.
- Arguments:
- function (function) - function to look up the original implementation of
+ :param function function: function to look up the original implementation of
- Returns:
- original implementation of the function
+ :returns: original implementation of the function
"""
if "mock_id" in function.__dict__:
@@ -196,15 +193,14 @@ def get_message(content, reformat = True):
"""
Provides a ControlMessage with content modified to be parsable. This makes
the following changes unless 'reformat' is false...
- - ensures the content ends with a newline
- - newlines are replaced with a carrage return and newline pair
- Arguments:
- content (str) - base content for the controller message
- reformat (str) - modifies content to be more accomidateing to being parsed
+ * ensures the content ends with a newline
+ * newlines are replaced with a carrage return and newline pair
+
+ :param str content: base content for the controller message
+ :param str reformat: modifies content to be more accomidateing to being parsed
- Returns:
- stem.socket.ControlMessage instance
+ :returns: stem.socket.ControlMessage instance
"""
if reformat:
@@ -219,11 +215,9 @@ def get_protocolinfo_response(**attributes):
base instance is minimal, with its version set to one and everything else
left with the default.
- Arguments:
- attributes (dict) - attributes to customize the response with
+ :param dict attributes: attributes to customize the response with
- Returns:
- stem.response.protocolinfo.ProtocolInfoResponse instance
+ :returns: stem.response.protocolinfo.ProtocolInfoResponse instance
"""
protocolinfo_response = get_message("250-PROTOCOLINFO 1\n250 OK")
diff --git a/test/output.py b/test/output.py
index db692af..bf7de7e 100644
--- a/test/output.py
+++ b/test/output.py
@@ -79,12 +79,10 @@ def apply_filters(testing_output, *filters):
output is either a string with the new content or None if the line should be
omitted.
- Arguments:
- testing_output (str) - output from the unit testing
- filters (list) - functors to be applied to each line of the results
+ :param str testing_output: output from the unit testing
+ :param list filters: functors to be applied to each line of the results
- Returns:
- str with the processed test results
+ :returns: str with the processed test results
"""
results = []
@@ -176,8 +174,7 @@ class ErrorTracker:
in which the user needs to look for failures. In practice this is mostly
used to specify the integ target we're running under.
- Arguments:
- category (str) - category to label errors as being under
+ :param str category: category to label errors as being under
"""
self._category = category
diff --git a/test/runner.py b/test/runner.py
index ebbd55b..8c01c3e 100644
--- a/test/runner.py
+++ b/test/runner.py
@@ -3,32 +3,34 @@ Runtime context for the integration tests. This is used both by the test runner
to start and stop tor, and by the integration tests themselves for information
about the tor test instance they're running against.
-RunnerStopped - Runner doesn't have an active tor instance
-TorInaccessable - Tor can't be queried for the information
+::
-require_control - skips the test unless tor provides a controller endpoint
-require_version - skips the test unless we meet a tor version requirement
-exercise_controller - basic sanity check that a controller connection can be used
-
-get_runner - Singleton for fetching our runtime context.
-Runner - Runtime context for our integration tests.
- |- start - prepares and starts a tor instance for our tests to run against
- |- stop - stops our tor instance and cleans up any temporary files
- |- is_running - checks if our tor test instance is running
- |- is_accessible - checks if our tor instance can be connected to
- |- is_ptraceable - checks if DisableDebuggerAttachment is set
- |- get_options - custom torrc options used for our test instance
- |- get_test_dir - testing directory path
- |- get_torrc_path - path to our tor instance's torrc
- |- get_torrc_contents - contents of our tor instance's torrc
- |- get_auth_cookie_path - path for our authentication cookie if we have one
- |- get_tor_cwd - current working directory of our tor process
- |- get_chroot - provides the path of our emulated chroot if we have one
- |- get_pid - process id of our tor process
- |- get_tor_socket - provides a socket to our test instance
- |- get_tor_controller - provides a controller for our test instance
- |- get_tor_version - provides the version of tor we're running against
- +- get_tor_command - provides the command used to start tor
+ RunnerStopped - Runner doesn't have an active tor instance
+ TorInaccessable - Tor can't be queried for the information
+
+ require_control - skips the test unless tor provides a controller endpoint
+ require_version - skips the test unless we meet a tor version requirement
+ exercise_controller - basic sanity check that a controller connection can be used
+
+ get_runner - Singleton for fetching our runtime context.
+ Runner - Runtime context for our integration tests.
+ |- start - prepares and starts a tor instance for our tests to run against
+ |- stop - stops our tor instance and cleans up any temporary files
+ |- is_running - checks if our tor test instance is running
+ |- is_accessible - checks if our tor instance can be connected to
+ |- is_ptraceable - checks if DisableDebuggerAttachment is set
+ |- get_options - custom torrc options used for our test instance
+ |- get_test_dir - testing directory path
+ |- get_torrc_path - path to our tor instance's torrc
+ |- get_torrc_contents - contents of our tor instance's torrc
+ |- get_auth_cookie_path - path for our authentication cookie if we have one
+ |- get_tor_cwd - current working directory of our tor process
+ |- get_chroot - provides the path of our emulated chroot if we have one
+ |- get_pid - process id of our tor process
+ |- get_tor_socket - provides a socket to our test instance
+ |- get_tor_controller - provides a controller for our test instance
+ |- get_tor_version - provides the version of tor we're running against
+ +- get_tor_command - provides the command used to start tor
"""
import os
@@ -91,18 +93,15 @@ RAN_TESTS = []
class RunnerStopped(Exception):
"Raised when we try to use a Runner that doesn't have an active tor instance"
- pass
class TorInaccessable(Exception):
"Raised when information is needed from tor but the instance we have is inaccessable"
- pass
def require_control(test_case):
"""
Skips the test unless tor provides an endpoint for controllers to attach to.
- Arguments:
- test_case (unittest.TestCase) - test being ran
+ :param unittest.TestCase test_case: test being ran
"""
if not test.runner.get_runner().is_accessible():
@@ -112,9 +111,8 @@ def require_version(test_case, req_version):
"""
Skips the test unless we meet the required version.
- Arguments:
- test_case (unittest.TestCase) - test being ran
- req_version (stem.version.Version) - required tor version for the test
+ :param unittest.TestCase test_case: test being ran
+ :param stem.version.Version req_version: required tor version for the test
"""
if get_runner().get_tor_version() < req_version:
@@ -124,11 +122,10 @@ def only_run_once(test_case, test_name):
"""
Skips the test if it has ran before. If it hasn't then flags it as being ran.
This is useful to prevent lengthy tests that are independent of integ targets
- from being run repeatedly with RUN_ALL.
+ from being run repeatedly with ``RUN_ALL``.
- Arguments:
- test_case (unittest.TestCase) - test being ran
- test_name (str) - name of the test being ran
+ :param unittest.TestCase test_case: test being ran
+ :param str test_name: name of the test being ran
"""
if (test_case, test_name) in RAN_TESTS:
@@ -139,12 +136,11 @@ def only_run_once(test_case, test_name):
def exercise_controller(test_case, controller):
"""
Checks that we can now use the socket by issuing a 'GETINFO config-file'
- query.
+ query. Controller can be either a :class:`stem.socket.ControlSocket` or
+ :class:`stem.control.BaseController`.
- Arguments:
- test_case (unittest.TestCase) - test being ran
- controller (stem.socket.ControlSocket or stem.control.BaseController) -
- tor controller connection to be authenticated
+ :param unittest.TestCase test_case: test being ran
+ :param controller: tor controller connection to be authenticated
"""
runner = get_runner()
@@ -161,6 +157,8 @@ def exercise_controller(test_case, controller):
def get_runner():
"""
Singleton for the runtime context of integration tests.
+
+ :returns: :class:`test.runner.Runner` with context for our integration tests
"""
global INTEG_RUNNER
@@ -203,12 +201,10 @@ class Runner:
Makes temporary testing resources and starts tor, blocking until it
completes.
- Arguments:
- tor_cmd (str) - command to start tor with
- extra_torrc_opts (list) - additional torrc options for our test instance
+ :param str tor_cmd: command to start tor with
+ :param list extra_torrc_opts: additional torrc options for our test instance
- Raises:
- OSError if unable to run test preparations or start tor
+ :raises: OSError if unable to run test preparations or start tor
"""
with self._runner_lock:
@@ -310,8 +306,7 @@ class Runner:
"""
Checks if we're running a tor test instance and that it's alive.
- Returns:
- True if we have a running tor test instance, False otherwise
+ :returns: True if we have a running tor test instance, False otherwise
"""
with self._runner_lock:
@@ -329,8 +324,7 @@ class Runner:
"""
Checks if our tor instance has a method of being connected to or not.
- Returns:
- True if tor has a control socket or port, False otherwise
+ :returns: True if tor has a control socket or port, False otherwise
"""
return Torrc.PORT in self._custom_opts or Torrc.SOCKET in self._custom_opts
@@ -338,11 +332,10 @@ class Runner:
def is_ptraceable(self):
"""
Checks if tor's 'DisableDebuggerAttachment' option is set. This feature has
- a lot of adverse side effects as per...
- https://trac.torproject.org/projects/tor/ticket/3313
+ a lot of adverse side effects
+ (`ticket <https://trac.torproject.org/projects/tor/ticket/3313>`_).
- Returns:
- True if debugger attachment is disallowd, False otherwise
+ :returns: True if debugger attachment is disallowd, False otherwise
"""
# If we're running a tor version where ptrace is disabled and we didn't
@@ -356,8 +349,7 @@ class Runner:
"""
Provides the custom torrc options our tor instance is running with.
- Returns:
- list of Torrc enumerations being used by our test instance
+ :returns: list of Torrc enumerations being used by our test instance
"""
return self._custom_opts
@@ -366,14 +358,11 @@ class Runner:
"""
Provides the absolute path for our testing directory or a file within it.
- Arguments:
- resource (str) - file within our test directory to provide the path for
+ :param str resource: file within our test directory to provide the path for
- Returns:
- str with our test direcectory's absolute path or that of a file within it
+ :returns: str with our test direcectory's absolute path or that of a file within it
- Raises:
- RunnerStopped if we aren't running
+ :raises: :class:`test.runner.RunnerStopped` if we aren't running
"""
if resource:
@@ -385,15 +374,11 @@ class Runner:
"""
Provides the absolute path for where our testing torrc resides.
- Arguments:
- ignore_chroot (bool) - provides the real path, rather than the one that
- tor expects if True
+ :param bool ignore_chroot: provides the real path, rather than the one that tor expects if True
- Returns:
- str with our torrc path
+ :returns: str with our torrc path
- Raises:
- RunnerStopped if we aren't running
+ :raises: RunnerStopped if we aren't running
"""
test_dir = self._get("_test_dir")
@@ -408,11 +393,9 @@ class Runner:
"""
Provides the contents of our torrc.
- Returns:
- str with the contents of our torrc, lines are newline separated
+ :returns: str with the contents of our torrc, lines are newline separated
- Raises:
- RunnerStopped if we aren't running
+ :raises: :class:`test.runner.RunnerStopped` if we aren't running
"""
return self._get("_torrc_contents")
@@ -423,11 +406,9 @@ class Runner:
If running with an emulated chroot this is uneffected, still providing the
real path.
- Returns:
- str with our auth cookie path
+ :returns: str with our auth cookie path
- Raises:
- RunnerStopped if we aren't running
+ :raises: :class:`test.runner.RunnerStopped` if we aren't running
"""
test_dir = self._get("_test_dir")
@@ -445,8 +426,7 @@ class Runner:
Provides the path we're using to emulate a chroot environment. This is None
if we aren't emulating a chroot setup.
- Returns:
- str with the path of our emulated chroot
+ :returns: str with the path of our emulated chroot
"""
return self._chroot_path
@@ -455,11 +435,9 @@ class Runner:
"""
Provides the process id of the tor process.
- Returns:
- int pid for the tor process
+ :returns: int pid for the tor process
- Raises:
- RunnerStopped if we aren't running
+ :raises: :class:`test.runner.RunnerStopped` if we aren't running
"""
tor_process = self._get("_tor_process")
@@ -469,14 +447,11 @@ class Runner:
"""
Provides a socket connected to our tor test instance.
- Arguments:
- authenticate (bool) - if True then the socket is authenticated
+ :param bool authenticate: if True then the socket is authenticated
- Returns:
- stem.socket.ControlSocket connected with our testing instance
+ :returns: :class:`stem.socket.ControlSocket` connected with our testing instance
- Raises:
- TorInaccessable if tor can't be connected to
+ :raises: :class:`test.runner.TorInaccessable` if tor can't be connected to
"""
if Torrc.PORT in self._custom_opts:
@@ -494,14 +469,11 @@ class Runner:
"""
Provides a controller connected to our tor test instance.
- Arguments:
- authenticate (bool) - if True then the socket is authenticated
+ :param bool authenticate: if True then the socket is authenticated
- Returns:
- stem.socket.Controller connected with our testing instance
+ :returns: :class:`stem.socket.Controller` connected with our testing instance
- Raises:
- TorInaccessable if tor can't be connected to
+ :raises: :class: `test.runner.TorInaccessable` if tor can't be connected to
"""
control_socket = self.get_tor_socket(authenticate)
@@ -511,8 +483,7 @@ class Runner:
"""
Queries our test instance for tor's version.
- Returns:
- stem.version.Version for our test instance
+ :returns: :class:`stem.version.Version` for our test instance
"""
try:
@@ -544,14 +515,11 @@ class Runner:
Fetches one of our attributes in a thread safe manner, raising if we aren't
running.
- Arguments:
- attr (str) - class variable that we want to fetch
+ :param str attr: class variable that we want to fetch
- Returns:
- value of the fetched variable
+ :returns: value of the fetched variable
- Raises:
- RunnerStopped if we aren't running
+ :returns: :class:`test.runner.RunnerStopped` if we aren't running
"""
with self._runner_lock:
@@ -563,8 +531,7 @@ class Runner:
"""
Makes a temporary runtime resources of our integration test instance.
- Raises:
- OSError if unsuccessful
+ :raises: OSError if unsuccessful
"""
# makes a temporary data directory if needed
@@ -648,12 +615,9 @@ class Runner:
Initializes a tor process. This blocks until initialization completes or we
error out.
- Arguments:
- tor_cmd (str) - command to start tor with
+ :param str tor_cmd: command to start tor with
- Raises:
- OSError if we either fail to create the tor process or reached a timeout
- without success
+ :raises: OSError if we either fail to create the tor process or reached a timeout without success
"""
test.output.print_line("Starting tor...\n", *STATUS_ATTR)
diff --git a/test/unit/control/__init__.py b/test/unit/control/__init__.py
deleted file mode 100644
index 448a597..0000000
--- a/test/unit/control/__init__.py
+++ /dev/null
@@ -1,6 +0,0 @@
-"""
-Unit tests for stem.control.
-"""
-
-__all__ = ["controller"]
-
diff --git a/test/unit/descriptor/extrainfo_descriptor.py b/test/unit/descriptor/extrainfo_descriptor.py
index 3bfff70..888180c 100644
--- a/test/unit/descriptor/extrainfo_descriptor.py
+++ b/test/unit/descriptor/extrainfo_descriptor.py
@@ -22,12 +22,10 @@ def _make_descriptor(attr = None, exclude = None):
"""
Constructs a minimal extrainfo descriptor with the given attributes.
- Arguments:
- attr (dict) - keyword/value mappings to be included in the descriptor
- exclude (list) - mandatory keywords to exclude from the descriptor
+ :param dict attr: keyword/value mappings to be included in the descriptor
+ :param list exclude: mandatory keywords to exclude from the descriptor
- Returns:
- str with customized descriptor content
+ :returns: str with customized descriptor content
"""
descriptor_lines = []
diff --git a/test/unit/descriptor/server_descriptor.py b/test/unit/descriptor/server_descriptor.py
index 6ad92b2..3bb2c7a 100644
--- a/test/unit/descriptor/server_descriptor.py
+++ b/test/unit/descriptor/server_descriptor.py
@@ -37,13 +37,11 @@ def _make_descriptor(attr = None, exclude = None, is_bridge = False):
"""
Constructs a minimal server descriptor with the given attributes.
- Arguments:
- attr (dict) - keyword/value mappings to be included in the descriptor
- exclude (list) - mandatory keywords to exclude from the descriptor
- is_bridge (bool) - minimal descriptor is for a bridge if True, relay otherwise
+ :param dict attr: keyword/value mappings to be included in the descriptor
+ :param list exclude: mandatory keywords to exclude from the descriptor
+ :param bool is_bridge: minimal descriptor is for a bridge if True, relay otherwise
- Returns:
- str with customized descriptor content
+ :returns: str with customized descriptor content
"""
descriptor_lines = []
More information about the tor-commits
mailing list