feat: implement test_client parameter

Author: azmeuk

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Versions follow [Semantic Versioning](https://semver.org/>) (<major>.<minor>.<patch>).
 
+## [0.2.0] - Unreleased
+
+### Added
+
+- Implement `test_client` attribute.
+- Implement `logout` method.
+
 ## [0.1.1] - 2025-04-04
 
 ### Changed

README.md

@@ -36,19 +36,19 @@ def test_authentication(iam_server, testapp, client):
     # create a random user on the IAM server
     user = iam_server.random_user()
 
-    # logs the user in give its consent to your application
-    iam_server.login(user)
-    iam_server.consent(user)
+    # 1. attempt to access a protected page, returns a redirection to the IAM
+    res = test_client.get("/protected")
 
-    # simulate an attempt to access a protected page of your app
-    response = testapp.get("/protected", status=302)
+    # 2. authorization code request
+    res = iam_server.test_client.get(res.location)
 
-    # get an authorization code request at the IAM
-    res = requests.get(res.location, allow_redirects=False)
+    # 3. load your application authorization endpoint
+    res = test_client.get(res.location)
 
-    # access to the redirection URI
-    res = testclient.get(res.headers["Location"])
-    res.mustcontain("Hello World!")
+    # 4. now you have access to the protected page
+    res = test_client.get("/protected")
+
+    assert "Hello, world!" in res.text
 ```
 
 Check the [client application](https://pytest-iam.readthedocs.io/en/latest/client-applications.html) or

doc/client-applications.rst

@@ -94,8 +94,8 @@ client registration. Here is an example of dynamic registration you can implemen
 
 .. code:: python
 
-    response = requests.post(
-        f"{iam_server.url}/oauth/register",
+    response = iam_server.test_client.post(
+        "/oauth/register",
         json={
             "client_name": "My application",
             "client_uri": "http://example.org",
@@ -106,53 +106,79 @@ client registration. Here is an example of dynamic registration you can implemen
             "scope": "openid profile groups",
         },
     )
-    client_id = response.json()["client_id"]
-    client_secret = response.json()["client_secret"]
+    client_id = response.json["client_id"]
+    client_secret = response.json["client_secret"]
 
 Nominal authentication case
 ---------------------------
 
 Let us suppose that your application have a ``/protected`` that redirects users
-to the IAM server if unauthenticated. With your :class:`~canaille.core.models.User`
-and :class:`~canaille.oidc.models.Client` fixtures, you can use the
-:meth:`~pytest_iam.Server.login` and :meth:`~pytest_iam.Server.consent` methods
-to skip the login and the consent page from the IAM.
-
+to the IAM server if unauthenticated.
 We suppose you have a test client fixture like werkzeug :class:`~werkzeug.test.Client`
-that allows to test your application endpoints without real HTTP requests. Let
-us see how to implement an authorization_code authentication test case:
+that allows to test your application endpoints without real HTTP requests.
+pytest-iam provides its own test client, available with :meth:`~pytest_iam.Server.test_client`.
+Let us see how to implement an authorization_code authentication test case:
 
-.. code:: python
+.. code-block:: python
+   :caption: Full login and consent workflow to get an access token
+
+    def test_login_and_consent(iam_server, client, user, test_client):
+        # 1. attempt to access a protected page
+        res = test_client.get("/protected")
+
+        # 2. redirect to the authorization server login page
+        res = iam_server.test_client.get(res.location)
+
+        # 3. fill the 'login' form at the IAM
+        res = iam_server.test_client.post(res.location, data={"login": "user"})
+
+        # 4. fill the 'password' form at the IAM
+        res = iam_server.test_client.post(
+            res.location, data={"password": "correct horse battery staple"}
+        )
+
+        # 5. fill the 'consent' form at the IAM
+        res = iam_server.test_client.post(res.location, data={"answer": "accept"})
+
+        # 6. load your application authorization endpoint
+        res = test_client.get(res.location)
 
-    def test_login_and_consent(iam_server, client, user, testclient):
+        # 7. now you have access to the protected page
+        res = test_client.get("/protected")
+
+What happened?
+
+1. A simulation of an access to a protected page on your application. As the page is protected,
+   it returns a redirection to the IAM login page.
+2. The IAM test client loads the login page and get redirected to the login form.
+3. The login form is filled, and returns a redirection to the password form.
+4. The password form is filled, and returns a redirection to the consent form.
+5. The consent form is filled, and return a redirection to your application authorization endpoint with a OAuth code grant.
+6. You client authorization endpoint is loaded, it reaches the IAM and exchanges the code grant with a token.   This is generally where you fill the session to keep users logged in.
+7. The protected page is loaded, and now you should be able to access it.
+
+Steps 2, 3 and 4 can be quite redundant, so pytest-iam provides shortcuts with the
+:meth:`~pytest_iam.Server.login` and :meth:`~pytest_iam.Server.consent` methods.
+They allow you to skip the login, password and consent pages:
+
+.. code-block:: python
+   :caption: Fast login and consent workflow to get an access token
+
+    def test_login_and_consent(iam_server, client, user, test_client):
         iam_server.login(user)
         iam_server.consent(user)
 
         # 1. attempt to access a protected page
-        res = testclient.get("/protected", status=302)
+        res = test_client.get("/protected")
 
         # 2. authorization code request
-        res = requests.get(res.location, allow_redirects=False)
+        res = iam_server.test_client.get(res.location)
 
         # 3. load your application authorization endpoint
-        res = testclient.get(res.headers["Location"], status=302)
-
-        # 4. redirect to the protected page
-        res = res.follow(status=200)
-
-What happened?
+        res = test_client.get(res.location)
 
-1. A simulation of an access to a protected page on your application.
-2. That redirects to the IAM authorization endpoint. Since the users are already
-   logged and their consent already given, the IAM redirects to your application
-   authorization configured redirect_uri, with the authorization code passed in
-   the query string. Note that ``requests`` is used in this example to perform
-   the request. Indeed, generally testclient such as the werkzeug one cannot
-   perform real HTTP requests.
-3. Access your application authorization endpoint that will exchange the
-   authorization code against a token and check the user credentials.
-4. For instance, your application can redirect the users back to the page
-   they attempted to access in the first place.
+        # 4. now you have access to the protected page
+        res = test_client.get("/protected")
 
 Error cases
 -----------

doc/resource-servers.rst

@@ -8,16 +8,16 @@ request against the identity server token introspection endpoint.
 
 .. code:: python
 
-    def test_valid_token_auth(iam_server, testclient, client, user):
+    def test_valid_token_auth(iam_server, test_client, client, user):
         token = iam_server.random_token(client=client, subject=user)
-        res = testclient.get(
+        res = test_client.get(
             "/protected-resource", headers={"Authorization": f"Bearer {token.access_token}"}
         )
         assert res.status_code == 200
 
 
-    def test_invalid_token_auth(iam_server, testclient):
-        res = testclient.get(
+    def test_invalid_token_auth(iam_server, test_client):
+        res = test_client.get(
             "/protected-resource", headers={"Authorization": "Bearer invalid"}
         )
         assert res.status_code == 401

pytest_iam/__init__.py

@@ -20,6 +20,7 @@
 from canaille.oidc.installation import generate_keypair
 from flask import Flask
 from flask import g
+from werkzeug.test import Client
 
 
 class Server:
@@ -31,6 +32,9 @@ class Server:
     app: Flask
     """The authorization server flask app."""
 
+    test_client: Client
+    """A test client to interact with the IAM without performing real network requests."""
+
     models: ModuleType
     """The module containing the available model classes."""
 
@@ -42,6 +46,7 @@ class Server:
 
     def __init__(self, app: Flask, port: int, backend: Backend, logging: bool = False):
         self.app = app
+        self.test_client = app.test_client()
         self.backend = backend
         self.port = port
         self.logging = logging
@@ -56,9 +61,19 @@ def __init__(self, app: Flask, port: int, backend: Backend, logging: bool = Fals
         def logged_user():
             if self.logged_user:
                 g.user = self.logged_user
+            else:
+                try:
+                    del g.user
+                except AttributeError:
+                    pass
 
             if self.login_datetime:
                 g.last_login_datetime = self.login_datetime
+            else:
+                try:
+                    del g.last_login_datetime
+                except AttributeError:
+                    pass
 
     def make_request_handler(self):
         server = self
@@ -131,6 +146,11 @@ def login(self, user):
         self.logged_user = user
         self.login_datetime = datetime.datetime.now(datetime.timezone.utc)
 
+    def logout(self):
+        """Close the current user session if existing."""
+        self.logged_user = None
+        self.login_datetime = None
+
     def consent(self, user, client=None):
         """Make a user consent to share data with OIDC clients.
 

tests/conftest.py

@@ -25,7 +25,7 @@ def user(iam_server):
         user_name="user",
         formatted_name="John Doe",
         emails=["[email protected]"],
-        password="password",
+        password="correct horse battery staple",
     )
     iam_server.backend.save(inst)
     yield inst

tests/test_client_application.py

@@ -1,21 +1,20 @@
 import uuid
 
 import pytest
-import requests
 from authlib.integrations.flask_client import OAuth
 from flask import Flask
 from flask import jsonify
 from flask import url_for
 
 
 def test_server_configuration(iam_server):
-    res = requests.get(f"{iam_server.url}/.well-known/openid-configuration")
-    assert res.json()["issuer"] in iam_server.url
+    res = iam_server.test_client.get("/.well-known/openid-configuration")
+    assert res.json["issuer"] in iam_server.url
 
 
 def test_client_dynamic_registration(iam_server):
-    response = requests.post(
-        f"{iam_server.url}/oauth/register",
+    response = iam_server.test_client.post(
+        "/oauth/register",
         json={
             "client_name": "Nubla Dashboard",
             "client_uri": "http://client.test",
@@ -26,17 +25,17 @@ def test_client_dynamic_registration(iam_server):
             "scope": "openid profile groups",
         },
     )
-    client_id = response.json()["client_id"]
-    client_secret = response.json()["client_secret"]
+    client_id = response.json["client_id"]
+    client_secret = response.json["client_secret"]
 
     client = iam_server.backend.get(iam_server.models.Client, client_id=client_id)
     assert client.client_secret == client_secret
     iam_server.backend.delete(client)
 
 
 def test_logs(iam_server, caplog):
-    response = requests.post(
-        f"{iam_server.url}/oauth/register",
+    response = iam_server.test_client.post(
+        "/oauth/register",
         json={
             "client_name": "Nubla Dashboard",
             "client_uri": "http://client.test",
@@ -50,7 +49,7 @@ def test_logs(iam_server, caplog):
 
     assert caplog.records[0].msg == "client registration endpoint request: POST: %s"
 
-    client_id = response.json()["client_id"]
+    client_id = response.json["client_id"]
     client = iam_server.backend.get(iam_server.models.Client, client_id=client_id)
     iam_server.backend.delete(client)
 
@@ -86,28 +85,64 @@ def authorize():
 
 
 @pytest.fixture
-def testclient(app):
+def test_client(app):
     app.config["TESTING"] = True
     return app.test_client()
 
 
-def test_login_and_consent(iam_server, client, user, testclient):
+def test_login_and_consent(iam_server, client, user, test_client):
+    # 1. attempt to access a protected page
+    res = test_client.get("/login")
+
+    # 2. redirect to the authorization server login page
+    res = iam_server.test_client.get(res.location)
+
+    # 3. fill the 'login' form
+    res = iam_server.test_client.post(res.location, data={"login": "user"})
+
+    # 4. fill the 'password' form
+    res = iam_server.test_client.post(
+        res.location, data={"password": "correct horse battery staple"}
+    )
+
+    # 5. fill the 'consent' form
+    res = iam_server.test_client.post(res.location, data={"answer": "accept"})
+
+    authorization = iam_server.backend.get(iam_server.models.AuthorizationCode)
+    assert authorization.client == client
+
+    # 6. load your application authorization endpoint
+    res = test_client.get(res.location)
+
+    token = iam_server.backend.get(iam_server.models.Token)
+    assert token.client == client
+
+    assert res.json["userinfo"]["sub"] == "user"
+    assert res.json["access_token"] == token.access_token
+
+    iam_server.logout()
+
+
+def test_prelogin_and_preconsent(iam_server, client, user, test_client):
     iam_server.login(user)
     iam_server.consent(user)
 
     # attempt to access a protected page
-    res = testclient.get("/login")
+    res = test_client.get("/login")
 
     # authorization code request (already logged in an consented)
-    res = requests.get(res.location, allow_redirects=False)
+    res = iam_server.test_client.get(res.location)
 
     authorization = iam_server.backend.get(iam_server.models.AuthorizationCode)
     assert authorization.client == client
 
-    res = testclient.get(res.headers["Location"])
+    # return to the client with a code
+    res = test_client.get(res.location)
 
     token = iam_server.backend.get(iam_server.models.Token)
     assert token.client == client
 
     assert res.json["userinfo"]["sub"] == "user"
     assert res.json["access_token"] == token.access_token
+
+    iam_server.logout()