Add example of using the Starlette test client with tox

This example Connexion app processes JSON requests and responses as specified
  with OpenAPI v2 (aka Swagger) or OpenAPI v3 file format.
The app asks Connexion to validate JSON responses against the spec.
The app defines an error handler that catches exceptions raised while processing a request.
Define automated tests that are run by tox.
Measure code lines covered by the automated tests.

Author: chrisinmtown

examples/testclient/README.rst

@@ -0,0 +1,60 @@
+===================
+Test Client Example
+===================
+
+This directory offers a Connexion app that processes a single JSON
+request and generates a response as specified with OpenAPI v2 (aka
+Swagger) or OpenAPI v3 file format. This example app demonstrates
+these test and validation features:
+* Validate generated responses against the specification
+* Catch and report exceptions raised while processing a request
+* Use tox and the Starlette test client to test the app automatically
+* Measure and report code lines covered by the automated tests
+
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0' tox
+
+Testing
+-------
+
+Run the test suite and generate the coverage report with this command:
+
+.. code-block:: bash
+
+    $ tox
+
+Running
+-------
+
+Launch the connexion server with this command:
+
+.. code-block:: bash
+
+    $ python app.py
+
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec
+
+Demonstrating
+-------------
+
+In the Swagger UI, click the "Try it out" button.  Send a request name and
+the app responds with a 200 status code and a greeting message "Hello <name>".  
+Next, demonstrate the app's validation features by sending a request with
+one of the following values in the request body's `message` parameter:
+* `crash` - the app raises an exception, which is caught by the exception handler;
+   you will see  an RFC 7807 "problem" response with `type`, `title`, `detail`
+   and `status` fields with the exception message.
+* `invalid` - the app generates an invalid response, which is caught by Connexion;
+   you will again see an RFC 7807 "problem" response with the failed-validation message.

examples/testclient/app.py

@@ -0,0 +1,64 @@
+import logging
+from pathlib import Path
+
+from connexion import FlaskApp
+from connexion.lifecycle import ConnexionRequest, ConnexionResponse
+from connexion.problem import problem
+
+# reuse the configured logger for simplicity
+logger = logging.getLogger("uvicorn.error")
+
+
+def handle_error(request: ConnexionRequest, ex: Exception) -> ConnexionResponse:
+    """
+    Report an error that happened while processing a request.
+    See: https://connexion.readthedocs.io/en/latest/exceptions.html
+
+    :param request: Request that failed
+    :parm ex: Exception that was raised
+    :return: ConnexionResponse with RFC7087 problem details
+    """
+    # log the request URL, exception and stack trace
+    logger.exception(
+        "Connexion caught exception on request to %s", request.url, exc_info=ex
+    )
+    return problem(title="Error", status=500, detail=repr(ex))
+
+
+def create_app() -> FlaskApp:
+    """
+    Create the connexion.FlaskApp, which wraps a Flask app.
+
+    :return Newly created connexion.FlaskApp
+    """
+    app = FlaskApp(__name__, specification_dir="spec/")
+    # hook the functions to the OpenAPI spec
+    title = {"title": "Hello World Plus Example"}
+    app.add_api("openapi.yaml", arguments=title, validate_responses=True)
+    app.add_api("swagger.yaml", arguments=title, validate_responses=True)
+    # hook a function that is invoked on any exception
+    app.add_error_handler(Exception, handle_error)
+    # return the fully initialized connexion.FlaskApp
+    return app
+
+
+def post_greeting(name: str, body: dict) -> tuple:
+    logger.info(
+        "%s: name len %d, body items %d", post_greeting.__name__, len(name), len(body)
+    )
+    # the body is optional
+    message = body.get("message", None)
+    if "crash" == message:
+        msg = f"Found message {message}, raise ValueError"
+        logger.info("%s", msg)
+        raise ValueError(msg)
+    if "invalid" == message:
+        logger.info("Found message %s, return invalid response", message)
+        return {"bogus": "response"}
+    return {"greeting": f"Hello {name}"}, 200
+
+
+# define app so loader can find it
+conn_app = create_app()
+if __name__ == "__main__":
+    conn_app.run(f"{Path(__file__).stem}:conn_app", port=8080)

examples/testclient/requirements.txt

@@ -0,0 +1 @@
+connexion[flask,swagger-ui,uvicorn]

examples/testclient/spec/openapi.yaml

@@ -0,0 +1,48 @@
+openapi: "3.0.0"
+
+info:
+  title: Hello World
+  version: "1.0"
+
+servers:
+  - url: /openapi
+
+paths:
+  /greeting/{name}:
+    post:
+      summary: Generate greeting
+      description: Generates a greeting message.
+      operationId: app.post_greeting
+      parameters:
+        - name: name
+          in: path
+          description: Name of the person to greet.
+          required: true
+          schema:
+            type: string
+            example: "dave"
+      requestBody:
+        description: >
+          Optional body with a message.
+          Send message "crash" or "invalid" to simulate an error.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                message:
+                  type: string
+                  example: "hi"
+      responses:
+        '200':
+          description: greeting response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  greeting:
+                    type: string
+                    example: "Hello John"
+                required:
+                  - greeting

examples/testclient/spec/swagger.yaml

@@ -0,0 +1,44 @@
+swagger: "2.0"
+
+info:
+  title: "{{title}}"
+  version: "1.0"
+
+basePath: /swagger
+
+paths:
+  /greeting/{name}:
+    post:
+      summary: Generate greeting
+      operationId: app.post_greeting
+      parameters:
+        - name: name
+          in: path
+          description: Name of the person to greet.
+          required: true
+          type: string
+        - name: body
+          in: body
+          description: >
+            Optional body with a message.
+            Send message "crash" or "invalid" to simulate an error.
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                example: "hi"
+      produces:
+        - application/json
+      responses:
+        '200':
+          description: greeting response
+          schema:
+            type: object
+            properties:
+              greeting:
+                type: string
+            required:
+              - greeting
+            example:
+              greeting: "Hello John"

examples/testclient/tests/__init__.py

@@ -0,0 +1,2 @@
+# empty __init__.py so that pytest can add correct path to coverage report
+# https://github.com/pytest-dev/pytest-cov/issues/98#issuecomment-451344057

examples/testclient/tests/conftest.py

@@ -0,0 +1,18 @@
+"""
+fixtures available for injection to tests by pytest
+"""
+import pytest
+from starlette.testclient import TestClient
+
+from app import conn_app
+
+
+@pytest.fixture
+def client():
+    """
+    Create a Connexion test_client from the Connexion app.
+
+    https://connexion.readthedocs.io/en/stable/testing.html
+    """
+    client: TestClient = conn_app.test_client()
+    yield client

examples/testclient/tests/test_app.py

@@ -0,0 +1,35 @@
+from httpx import Response
+from starlette.testclient import TestClient
+
+detail = "detail"
+greeting = "greeting"
+message = "message"
+prefixes = ["openapi", "swagger"]
+
+
+def test_greeting_dave(client: TestClient):
+    name = "dave"
+    for prefix in prefixes:
+        res: Response = client.post(
+            f"/{prefix}/{greeting}/{name}", json={message: "hi"}
+        )
+        assert res.status_code == 200
+        assert name in res.json()[greeting]
+
+
+def test_greeting_crash(client: TestClient):
+    crash = "crash"
+    for prefix in prefixes:
+        res: Response = client.post(f"/{prefix}/{greeting}/name", json={message: crash})
+        assert res.status_code == 500
+        assert crash in res.json()[detail]
+
+
+def test_greeting_invalid(client: TestClient):
+    for prefix in prefixes:
+        # a body is required in the POST
+        res: Response = client.post(
+            f"/{prefix}/{greeting}/name", json={message: "invalid"}
+        )
+        assert res.status_code == 500
+        assert "Response body does not conform" in res.json()[detail]

examples/testclient/tox.ini

@@ -0,0 +1,18 @@
+[tox]
+envlist = code
+minversion = 2.0
+
+[pytest]
+testpaths = tests
+
+[testenv:code]
+basepython = python3
+deps=
+    pytest
+    pytest-cov
+    pytest-mock
+    -r requirements.txt
+commands =
+    # posargs allows running just a single test like this:
+    # tox -- tests/test_foo.py::test_bar
+    pytest --cov --cov-report term-missing --cov-fail-under=70 {posargs}