Merge branch 'Auth'

Author: bjoern-otto

README.md

@@ -119,7 +119,18 @@ You may prefer the HTML output for better readability by running:
 ```sh
 aas_test_engines check_server http://my-server.com/api/v3.0 https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002 --output html > result.html
 ```
- 
+
+### Handling Authorization
+In case your server applies some authorization mechanism for security, you need to pass credentials to the Test Engines.
+You can use the `--header` option to do so by providing credentials within header fields:
+
+<!-- no-check -->
+```sh
+aas_test_engines check_server http://my-server.com/api/v3.0 https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002 --header 'Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l'
+```
+
+If you need a more sophisticated authorization mechanism, you should use the Python module interface and provide your own `aas_test_engines.http.HttpClient` class.
+
 ## Python Module Interface
 <a name="python-interface"></a>
 
@@ -199,23 +210,30 @@ result.dump()
 Check a running server instance:
 
 ```python
-from aas_test_engines import api
+from aas_test_engines import api, config, http
+
+client = http.HttpClient(
+    host="http://localhost",
+)
+conf = config.CheckApiConfig(
+    suite="https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002",
+)
 
-conf = api.ExecConf(server="http://localhost")
-result, mat = api.execute_tests(conf, "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002")
+result, mat = api.execute_tests(client, conf)
 result.dump()
 ```
 
-Checking older versions:
+To check older versions pass `version` to the `ApiConfig`:
 
 ```python
-from aas_test_engines import api
+from aas_test_engines import api, config
 print(api.supported_versions())
 print(api.latest_version())
 
-conf = api.ExecConf(server="http://localhost")
-result, mat = api.execute_tests(conf, "https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002", "3.0")
-result.dump()
+conf = config.CheckApiConfig(
+    suite="https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002",
+    version='3.0'
+)
 ```
 
 ### Generating test data for software testing

aas_test_engines/__main__.py

@@ -2,8 +2,9 @@
 import sys
 import os
 import json
-from aas_test_engines import api, file
+from aas_test_engines import api, config, file, http
 from enum import Enum
+from typing import Tuple
 
 # https://stackoverflow.com/questions/27981545
 import urllib3
@@ -26,6 +27,14 @@ class OutputFormats(Enum):
     HTML = "html"
 
 
+def _parse_header_value(s: str) -> Tuple[str, str]:
+    try:
+        key, value = s.split(":", 1)
+        return key.strip(), value.strip()
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"Invalid format for header:value: '{s}'")
+
+
 def run_file_test(argv):
     parser = argparse.ArgumentParser(description="Checks a file for compliance with the AAS meta-model")
     parser.add_argument("file", type=argparse.FileType("rb"), help="the file to check")
@@ -66,6 +75,13 @@ def run_api_test(argv):
     parser = argparse.ArgumentParser(description="Checks a server instance for compliance with the AAS api")
     parser.add_argument("server", type=str, help="server to run the tests against")
     parser.add_argument("suite", type=str, help="test suite (or substring of it)")
+    parser.add_argument(
+        "--header",
+        nargs="+",
+        default=[],
+        type=_parse_header_value,
+        help="Additional headers in the format header:value",
+    )
     parser.add_argument("--dry", action="store_true", help="dry run, do not send requests")
     parser.add_argument("--version", type=str, default=api.latest_version())
     parser.add_argument("--no-verify", action="store_true", help="do not check TLS certificate")
@@ -100,13 +116,19 @@ def run_api_test(argv):
     else:
         suite = suites[0]
 
-    exec_conf = api.ExecConf(
-        server=args.server,
-        dry=args.dry,
+    client = http.HttpClient(
+        host=args.server,
         verify=not args.no_verify,
         remove_path_prefix=args.remove_path_prefix,
+        additional_headers=dict(args.header),
+    )
+    conf = config.CheckApiConfig(
+        suite=suite,
+        version=args.version,
+        dry=args.dry,
     )
-    result, mat = api.execute_tests(exec_conf, suite, args.version)
+
+    result, mat = api.execute_tests(client, conf)
     if args.output == OutputFormats.TEXT:
         result.dump()
     elif args.output == OutputFormats.HTML:

aas_test_engines/api.py

@@ -1,9 +1,10 @@
 from typing import Dict, List, Tuple
-from aas_test_engines.test_cases.v3_0.api import ExecConf
 from aas_test_engines.test_cases.v3_0 import api as v3_0
 from fences.core.util import ConfusionMatrix
 from .result import AasTestResult
 from .exception import AasTestToolsException
+from .config import CheckApiConfig
+from .http import HttpClient
 
 _DEFAULT_VERSION = "3.0"
 
@@ -16,7 +17,8 @@ def latest_version():
     return _DEFAULT_VERSION
 
 
-def execute_tests(conf: ExecConf, suite: str, version: str = _DEFAULT_VERSION) -> Tuple[AasTestResult, ConfusionMatrix]:
+def execute_tests(client: HttpClient, conf: CheckApiConfig) -> Tuple[AasTestResult, ConfusionMatrix]:
+    version = conf.version or _DEFAULT_VERSION
     if version != _DEFAULT_VERSION:
         raise AasTestToolsException(f"Unknown version {version}, must be one of {supported_versions()}")
-    return v3_0.execute_tests(conf, suite)
+    return v3_0.execute_tests(client, conf)

aas_test_engines/config.py

@@ -0,0 +1,9 @@
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class CheckApiConfig:
+    suite: str
+    version: Optional[str] = None
+    dry: bool = False

aas_test_engines/http.py

@@ -1,4 +1,4 @@
-from typing import Tuple, Optional, List
+from typing import Tuple, Optional, List, Dict
 import requests
 from requests.models import Response
 from dataclasses import dataclass, field
@@ -35,14 +35,17 @@ def dump(self, body_max_chars=80):
 
 class HttpClient:
 
-    def __init__(self, host: str, verify: bool, remove_path_prefix: str):
+    def __init__(
+        self, host: str, verify: bool = False, remove_path_prefix: str = "", additional_headers: Dict[str, str] = {}
+    ):
         self.host = host
         self.verify = verify
         self.remove_path_prefix = remove_path_prefix
         self.prefixes: List[str] = []
+        self.additional_headers = additional_headers
 
     def descend(self, prefix: str):
-        result = HttpClient(self.host, self.verify, self.remove_path_prefix)
+        result = HttpClient(self.host, self.verify, self.remove_path_prefix, self.additional_headers)
         result.prefixes.append(prefix)
         return result
 

aas_test_engines/test_cases/v3_0/api.py

@@ -5,6 +5,7 @@
 from aas_test_engines.reflect import reflect_function
 from aas_test_engines.result import write, start, abort, Level, AasTestResult
 from aas_test_engines.http import HttpClient, Request
+from aas_test_engines.config import CheckApiConfig
 import requests
 from .interfaces import (
     aas,
@@ -18,14 +19,6 @@
 from .generate import generate_calls
 
 
-@dataclass
-class ExecConf:
-    server: str
-    dry: bool = False
-    verify: bool = True
-    remove_path_prefix: str = ""
-
-
 SSP_PREFIX = "https://admin-shell.io/aas/API/3/0/"
 
 
@@ -224,17 +217,16 @@ def _execute(suite: ApiTestSuite) -> ConfusionMatrix:
     return mat
 
 
-def execute_tests(conf: ExecConf, suite: str) -> Tuple[AasTestResult, ConfusionMatrix]:
+def execute_tests(client: HttpClient, conf: CheckApiConfig) -> Tuple[AasTestResult, ConfusionMatrix]:
     try:
-        test_suites = available_suites[suite]
+        test_suites = available_suites[conf.suite]
     except KeyError:
         all_suites = "\n".join(sorted(available_suites.keys()))
-        raise AasTestToolsException(f"Unknown suite {suite}, must be one of:\n{all_suites}")
+        raise AasTestToolsException(f"Unknown suite {conf.suite}, must be one of:\n{all_suites}")
 
     mat = ConfusionMatrix()
-    client = HttpClient(conf.server, conf.verify, conf.remove_path_prefix)
 
-    with start(f"Checking compliance to {suite}") as result_root:
+    with start(f"Checking compliance to {conf.suite}") as result_root:
 
         # Initial connection check
         if not _check_server(conf.dry, client):
@@ -253,7 +245,7 @@ def execute_tests(conf: ExecConf, suite: str) -> Tuple[AasTestResult, ConfusionM
                 with start("Setup") as result_setup:
                     prefix = prefix_provider(client)
                     sub_client = client.descend(prefix)
-                    test_suite: ApiTestSuite = test_suite_class(sub_client, suite)
+                    test_suite: ApiTestSuite = test_suite_class(sub_client, conf.suite)
                     test_suite.setup()
 
                 if result_setup.ok():

bin/check_servers.py

@@ -8,7 +8,7 @@
 from dataclasses import dataclass, field
 import base64
 
-from aas_test_engines.api import execute_tests, ExecConf
+from aas_test_engines.api import execute_tests, CheckApiConfig, HttpClient
 import requests
 from fences.core.util import ConfusionMatrix, Table, print_table
 
@@ -129,12 +129,15 @@ def main():
 
             docker_compose(server_dir, 'up', '-d')
             wait_for_server(server.url + "/shells")
-            conf = ExecConf(
-                server=server.url + profile.url_suffix,
+            client = HttpClient(
+                host=server.url + profile.url_suffix,
+                remove_path_prefix=profile.discard_prefix,
                 verify=False,
-                remove_path_prefix=profile.discard_prefix
             )
-            result, mat = execute_tests(conf, profile.spec_name)
+            conf = CheckApiConfig(
+                suite=profile.spec_name,
+            )
+            result, mat = execute_tests(client, conf)
             with open(result_file, "w") as f:
                 f.write(result.to_html())
             profile.mats.append(mat)

test/acceptance/server.py

@@ -1,6 +1,6 @@
 #! /usr/bin/env python3
 
-from aas_test_engines import api
+from aas_test_engines import api, config, http
 import os
 import shutil
 import subprocess
@@ -107,11 +107,12 @@ class Params:
 for param in params:
     print("-" * 10)
     print(f"Checking {param.suite}")
-    conf = api.ExecConf(
-        server=f"{HOST}{param.url}",
+    client = http.HttpClient(
+        host=f"{HOST}{param.url}",
         remove_path_prefix=param.remove_path_prefix,
     )
-    result, mat = api.execute_tests(conf, param.suite)
+    conf = config.CheckApiConfig(param.suite)
+    result, mat = api.execute_tests(client, conf)
     mat.print()
     with open("output.html", "w") as f:
         f.write(result.to_html())