Changeset 0560bb9 in mod_gnutls

Timestamp:

Dec 6, 2019, 11:10:38 AM (3 years ago)

Author:

Fiona Klute <fiona.klute@…>

Branches:

asyncio, main, master, proxy-ticket

Children:

f6d2721

Parents:

f9e13a5

Message:

Add some documentation for the Python test modules

Location:

test/mgstest

Files:

• __init__.py (modified) (1 diff)
• http.py (modified) (2 diffs)
• tests.py (modified) (5 diffs)

test/mgstest/__init__.py

@@ -15 +15 @@
 # limitations under the License.
 
+"""Python modules for the mod_gnutls test suite."""
+
 class TestExpectationFailed(Exception):
     """Raise if a test failed. The constructor should be called with a

test/mgstest/http.py

@@ -15 +15 @@
 # limitations under the License.
 
+"""HTTP handling components for mod_gnutls tests."""
+
 import socket
 import subprocess
@@ -22 +24 @@
 
 class HTTPSubprocessConnection(HTTPConnection):
+    """An HTTPConnection that transports data through a subprocess instead
+    of a socket. The mod_gnutls test suite uses it to transport data
+    through gnutls-cli instead of the ssl module.
+
+    """
     def __init__(self, command, host, port=None,
                  output_filter=None,

test/mgstest/tests.py

@@ -15 +15 @@
 # limitations under the License.
 
+"""Test objects and support functions for the mod_gnutls test
+suite. The classes defined in this module represent structures in the
+YAML test configuration files.
+
+"""
+
 import re
 import subprocess
@@ -23 +29 @@
 
 class TestConnection(yaml.YAMLObject):
+    """An HTTP connection in a test. It includes parameters for the
+    transport (currently gnutls-cli only), and the actions
+    (e.g. sending requests) to take using this connection.
+
+    Note that running one TestConnection object may result in multiple
+    sequential network connections, if the transport gets closed in a
+    non-failure way (e.g. following a "Connection: close" request) and
+    there are more actions, or (rarely) if an action requires its own
+    transport.
+
+    """
     yaml_tag = '!connection'
 
@@ -66 +83 @@
 
 class TestRequest(yaml.YAMLObject):
+    """Test action that sends an HTTP/1.1 request.
+
+    The path must be specified in the configuration file, all other
+    parameters (method, headers, expected response) have
+    defaults.
+
+    Options for checking the response currently are:
+    * require a specific response status
+    * require the body to exactly match a specific string
+    * require the body to contain all of a list of strings
+
+    """
     yaml_tag = '!request'
     def __init__(self, path, method='GET', headers=dict(),
@@ -161 +190 @@
 
 class TestRaw10(TestRequest):
-    """This is a minimal (and likely incomplete) HTTP/1.0 test client for
-    the one test case that strictly requires HTTP/1.0. All request
-    parameters (method, path, headers) MUST be specified in the config
-    file.
+    """Test action that sends a request using a minimal (and likely
+    incomplete) HTTP/1.0 test client for the one test case that
+    strictly requires HTTP/1.0.
+
+    All request parameters (method, path, headers) MUST be specified
+    in the config file. Checks on status and body work the same as for
+    TestRequest.
 
     """
@@ -228 +260 @@
 
 def filter_cert_log(in_stream, out_stream):
+    """Filter to stop an erroneous gnutls-cli log message.
+
+    This function filters out a log line about loading client
+    certificates that is mistakenly sent to stdout from gnutls-cli. My
+    fix (https://gitlab.com/gnutls/gnutls/merge_requests/1125) has
+    been merged, but buggy binaries will probably be around for a
+    while.
+
+    The filter is meant to run in a multiprocessing.Process or
+    threading.Thread that receives the stdout of gnutls-cli as
+    in_stream, and a connection for further processing as out_stream.
+
+    """
     import fcntl
     import os
     import select
-    # This filters out a log line about loading client
-    # certificates that is mistakenly sent to stdout. My fix has
-    # been merged, but buggy binaries will probably be around for
-    # a while.
-    # https://gitlab.com/gnutls/gnutls/merge_requests/1125
+    # message to filter
     cert_log = b'Processed 1 client X.509 certificates...\n'