first commit

docs/TESTING.md

@@ -0,0 +1,60 @@
+# Testing Guide
+
+This document outlines the current testing strategy for the OIDC server and provides instructions on how to perform tests.
+
+## Overview
+
+Currently, the project relies on manual testing using a simple Flask-based OIDC client application (`test_client.py`). This test client is designed to simulate a real-world application and allows you to walk through the entire OIDC Authorization Code Flow.
+
+There is not yet a suite of automated unit or integration tests. Adding a formal testing framework like PyTest is a key goal for future development (see `TODO.md`).
+
+## Running the Test Client
+
+The test client is a separate Flask application that runs on port `8080`. To use it, you need to have both the main OIDC server and the test client running at the same time.
+
+### Step 1: Run the OIDC Server
+
+In one terminal, start the main OIDC server (either with Docker or locally). For testing, it's easiest to run it locally:
+
+```bash
+# In your first terminal
+export FLASK_APP=oidc_server.py
+export FLASK_ENV=development
+
+# Make sure your database is up-to-date
+flask db upgrade
+flask seed
+
+# Run the OIDC server (defaults to port 5000)
+flask run
+```
+
+### Step 2: Run the Test Client
+
+The test client is pre-configured to work with the default settings of the OIDC server running on `localhost:5000`.
+
+In a second terminal, run the `test_client.py` application:
+
+```bash
+# In your second terminal
+python3 test_client.py
+```
+
+This will start the test client on `http://localhost:8080`.
+
+### Step 3: Perform the Test
+
+1.  **Open your browser** and navigate to the test client's URL: `http://localhost:8080`.
+2.  **Click the "Mit OIDC einloggen" button.** This will redirect you to the OIDC server's login page.
+3.  **Log in** with one of the test user accounts (e.g., `test` / `test123`).
+4.  **Successful Login**: After a successful login, the OIDC server will redirect you back to the test client's callback URL (`/callback`).
+5.  **Token Exchange**: The test client will automatically exchange the received authorization code for an access token and an ID token.
+6.  **View Results**: The test client's homepage will now display the user information retrieved from the `/userinfo` endpoint, as well as the contents of the access token and the ID token.
+
+This process allows you to manually verify that the entire OIDC flow is working as expected.
+
+## Future Improvements
+
+-   **Automated Integration Tests**: The `test_client.py` could be extended to make automated requests and assertions instead of requiring manual browser interaction.
+-   **Unit Tests**: A suite of unit tests should be created to test individual functions and components in isolation (e.g., model logic, specific OIDC validation rules).
+-   **PyTest Framework**: The project should adopt the PyTest framework for writing and running tests in a structured way.