oicd/docs/TESTING.md

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:

# 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:

# 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.