Changeset bbc9b03 in mod_gnutls

Timestamp:

Jan 4, 2020, 12:19:55 PM (3 years ago)

Author:

Fiona Klute <fiona.klute@…>

Branches:

asyncio, main, master, proxy-ticket

Children:

a47c201

Parents:

8510282

git-author:

Fiona Klute <fiona.klute@…> (01/04/20 12:13:22)

git-committer:

Fiona Klute <fiona.klute@…> (01/04/20 12:19:55)

Message:

Detailed documentation on test.yml and mgstest.tests

Location:

test

Files:

• README.md (modified) (1 diff)
• mgstest/tests.py (modified) (9 diffs)
• sample_test.yml (modified) (1 diff)

test/README.md

@@ -80 +80 @@
 
 * `test.yml` -- Defines the client connection(s) including parameters
-  for gnutls-cli, the request(s), and expected response(s)
+  for `gnutls-cli`, the request(s), and expected response(s). Please
+  see the module documentation of [mgstest.tests](./mgstest/tests.py)
+  for details, and [`sample_test.yml`](./sample_test.yml) and
+  [`sample_fail.yml`](./sample_fail.yml) for examples.
 
 * `backend.conf` [optional] -- Apache configuration for the proxy

test/mgstest/tests.py

@@ -19 +19 @@
 YAML test configuration files.
 
+The test configuration file defines either a TestConnection, or a list
+of them. Each connection contains a list of actions to run using this
+connection. The actions define their expected results, if an
+expectation is not met mgstest.TestExpectationFailed is raised.
+
+Example of a connection that runs two request actions, which are
+expected to succeed:
+
+```yaml
+!connection
+# "host" defaults to $TEST_TARGET, so usually there's no need to set
+# it. You can use ${VAR} to substitute environment variables.
+host: 'localhost'
+# "port" defaults to $TEST_PORT, so usually there's no need to set it
+# it. You can use ${VAR} to substitute environment variables.
+port: '${TEST_PORT}'
+# All elements of gnutls_params will be prefixed with "--" and passed
+# to gnutls-cli on the command line.
+gnutls_params:
+  - x509cafile=authority/x509.pem
+# The transport encryption. "Gnutls" is the default, "plain" can be
+# set to get an unencrypted connection (e.g. to test redirection to
+# HTTPS).
+transport: 'gnutls'
+description='This connection description will be logged.'
+actions:
+  - !request
+    # GET is the default.
+    method: GET
+    # The path part of the URL, required.
+    path: /test.txt
+    # "Expect" defines how the response must look to pass the test.
+    expect:
+      # 200 (OK) is the default.
+      status: 200
+      # The response body is analyzed only if the "body" element
+      # exists, otherwise any content is accepted.
+      body:
+        # The full response body must exactly match this string.
+        exactly: |
+          test
+  - !request
+    path: /status?auto
+    expect:
+      # The headers are analyzed only if the "headers" element exists.
+      headers:
+        # The Content-Type header must be present with exactly this
+        # value. You can use ${VAR} to substitute environment
+        # variables in the value.
+        Content-Type: 'text/plain; charset=ISO-8859-1'
+      body:
+        # All strings in this list must occur in the body, in any
+        # order. "Contains" may also contain a single string instead
+        # of a list.
+        contains:
+          - 'Using GnuTLS version: '
+          - 'Current TLS session: (TLS1.3)'
+```
+
+Example of a connection that is expected to fail at the TLS level, in
+this case because the configured CA is not the one that issued the
+server certificate:
+
+```yaml
+- !connection
+  gnutls_params:
+    - x509cafile=rogueca/x509.pem
+  actions:
+    - !request
+      path: /
+      expect:
+        # The connection is expected to reset without an HTTP response.
+        reset: yes
+```
+
 """
 
@@ -36 +111 @@
 
 class Transports(Enum):
+    """Transports supported by TestConnection."""
     GNUTLS = auto()
     PLAIN = auto()
@@ -44 +120 @@
 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.
+    transport, 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
+    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
@@ -79 +155 @@
 
     def run(self, timeout=5.0, conn_log=None, response_log=None):
+        """Set up an HTTP connection and run the configured actions."""
+
         # note: "--logfile" option requires GnuTLS version >= 3.6.7
         command = ['gnutls-cli', '--logfile=/dev/stderr']
@@ -123 +201 @@
     Options for checking the response currently are:
     * require a specific response status
+    * require specific headers to be present with specific values
     * require the body to exactly match a specific string
     * require the body to contain all of a list of strings
@@ -243 +322 @@
     strictly requires HTTP/1.0.
 
-    Objects use the same default parameters as TestRequest, but note
-    that an empty "headers" parameter means that not even a "Host:"
-    header will be sent. All headers must be specified in the test
-    configuration file.
+    TestReq10 objects use the same YAML parameters and defaults as
+    TestRequest, but note that an empty "headers" parameter means that
+    not even a "Host:" header will be sent. All headers must be
+    specified in the test configuration file.
 
     """
@@ -362 +441 @@
 
 def format_response(resp, body):
+    """Format an http.client.HTTPResponse for logging."""
     s = f'{resp.status} {resp.reason}\n'
     s = s + '\n'.join(f'{name}: {value}' for name, value in resp.getheaders())
@@ -370 +450 @@
 
 def subst_env(text):
+    """Use the parameter "text" as a template, substitute with environment
+    variables.
+
+    >>> os.environ['EXAMPLE_VAR'] = 'abc'
+    >>> subst_env('${EXAMPLE_VAR}def')
+    'abcdef'
+
+    """
     t = Template(text)
     return t.substitute(os.environ)
@@ -376 +464 @@
 
 def run_test_conf(test_config, timeout=5.0, conn_log=None, response_log=None):
+    """Load and run a test configuration.
+
+    The test_conf parameter must be a YAML file, defining one or more
+    TestConnections, to be run in order. The other three parameters
+    are forwarded to TestConnection.run().
+
+    """
     conns = None
 

test/sample_test.yml

@@ -25 +25 @@
       body:
         contains:
+          - 'Using GnuTLS version: '
           - 'Current TLS session: (TLS1.3)'