Changeset bbc9b03 in mod_gnutls for test/mgstest/tests.py


Ignore:
Timestamp:
Jan 4, 2020, 12:19:55 PM (5 months ago)
Author:
Fiona Klute <fiona.klute@…>
Branches:
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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • test/mgstest/tests.py

    r8510282 rbbc9b03  
    1919YAML test configuration files.
    2020
     21The test configuration file defines either a TestConnection, or a list
     22of them. Each connection contains a list of actions to run using this
     23connection. The actions define their expected results, if an
     24expectation is not met mgstest.TestExpectationFailed is raised.
     25
     26Example of a connection that runs two request actions, which are
     27expected to succeed:
     28
     29```yaml
     30!connection
     31# "host" defaults to $TEST_TARGET, so usually there's no need to set
     32# it. You can use ${VAR} to substitute environment variables.
     33host: 'localhost'
     34# "port" defaults to $TEST_PORT, so usually there's no need to set it
     35# it. You can use ${VAR} to substitute environment variables.
     36port: '${TEST_PORT}'
     37# All elements of gnutls_params will be prefixed with "--" and passed
     38# to gnutls-cli on the command line.
     39gnutls_params:
     40  - x509cafile=authority/x509.pem
     41# The transport encryption. "Gnutls" is the default, "plain" can be
     42# set to get an unencrypted connection (e.g. to test redirection to
     43# HTTPS).
     44transport: 'gnutls'
     45description='This connection description will be logged.'
     46actions:
     47  - !request
     48    # GET is the default.
     49    method: GET
     50    # The path part of the URL, required.
     51    path: /test.txt
     52    # "Expect" defines how the response must look to pass the test.
     53    expect:
     54      # 200 (OK) is the default.
     55      status: 200
     56      # The response body is analyzed only if the "body" element
     57      # exists, otherwise any content is accepted.
     58      body:
     59        # The full response body must exactly match this string.
     60        exactly: |
     61          test
     62  - !request
     63    path: /status?auto
     64    expect:
     65      # The headers are analyzed only if the "headers" element exists.
     66      headers:
     67        # The Content-Type header must be present with exactly this
     68        # value. You can use ${VAR} to substitute environment
     69        # variables in the value.
     70        Content-Type: 'text/plain; charset=ISO-8859-1'
     71      body:
     72        # All strings in this list must occur in the body, in any
     73        # order. "Contains" may also contain a single string instead
     74        # of a list.
     75        contains:
     76          - 'Using GnuTLS version: '
     77          - 'Current TLS session: (TLS1.3)'
     78```
     79
     80Example of a connection that is expected to fail at the TLS level, in
     81this case because the configured CA is not the one that issued the
     82server certificate:
     83
     84```yaml
     85- !connection
     86  gnutls_params:
     87    - x509cafile=rogueca/x509.pem
     88  actions:
     89    - !request
     90      path: /
     91      expect:
     92        # The connection is expected to reset without an HTTP response.
     93        reset: yes
     94```
     95
    2196"""
    2297
     
    36111
    37112class Transports(Enum):
     113    """Transports supported by TestConnection."""
    38114    GNUTLS = auto()
    39115    PLAIN = auto()
     
    44120class TestConnection(yaml.YAMLObject):
    45121    """An HTTP connection in a test. It includes parameters for the
    46     transport (currently gnutls-cli only), and the actions
    47     (e.g. sending requests) to take using this connection.
     122    transport, and the actions (e.g. sending requests) to take using
     123    this connection.
    48124
    49125    Note that running one TestConnection object may result in multiple
    50     sequential network connections, if the transport gets closed in a
     126    sequential network connections if the transport gets closed in a
    51127    non-failure way (e.g. following a "Connection: close" request) and
    52128    there are more actions, or (rarely) if an action requires its own
     
    79155
    80156    def run(self, timeout=5.0, conn_log=None, response_log=None):
     157        """Set up an HTTP connection and run the configured actions."""
     158
    81159        # note: "--logfile" option requires GnuTLS version >= 3.6.7
    82160        command = ['gnutls-cli', '--logfile=/dev/stderr']
     
    123201    Options for checking the response currently are:
    124202    * require a specific response status
     203    * require specific headers to be present with specific values
    125204    * require the body to exactly match a specific string
    126205    * require the body to contain all of a list of strings
     
    243322    strictly requires HTTP/1.0.
    244323
    245     Objects use the same default parameters as TestRequest, but note
    246     that an empty "headers" parameter means that not even a "Host:"
    247     header will be sent. All headers must be specified in the test
    248     configuration file.
     324    TestReq10 objects use the same YAML parameters and defaults as
     325    TestRequest, but note that an empty "headers" parameter means that
     326    not even a "Host:" header will be sent. All headers must be
     327    specified in the test configuration file.
    249328
    250329    """
     
    362441
    363442def format_response(resp, body):
     443    """Format an http.client.HTTPResponse for logging."""
    364444    s = f'{resp.status} {resp.reason}\n'
    365445    s = s + '\n'.join(f'{name}: {value}' for name, value in resp.getheaders())
     
    370450
    371451def subst_env(text):
     452    """Use the parameter "text" as a template, substitute with environment
     453    variables.
     454
     455    >>> os.environ['EXAMPLE_VAR'] = 'abc'
     456    >>> subst_env('${EXAMPLE_VAR}def')
     457    'abcdef'
     458
     459    """
    372460    t = Template(text)
    373461    return t.substitute(os.environ)
     
    376464
    377465def run_test_conf(test_config, timeout=5.0, conn_log=None, response_log=None):
     466    """Load and run a test configuration.
     467
     468    The test_conf parameter must be a YAML file, defining one or more
     469    TestConnections, to be run in order. The other three parameters
     470    are forwarded to TestConnection.run().
     471
     472    """
    378473    conns = None
    379474
Note: See TracChangeset for help on using the changeset viewer.