Improve the entire specification test suite (#17)

* Improved the spec tests by adding some tests for the session service

* style: Apply automated code formatting [skip ci]

* Test commit to trigger the workflow runs

* Added more tests to better verify the auth

* style: Apply automated code formatting [skip ci]

* Added more tests to better verify the auth

* Encapsulated all the specificiation tests into classes

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: mridang

spec/auth/using_access_token_spec.py

@@ -0,0 +1,62 @@
+import os
+
+import pytest
+
+import zitadel_client as zitadel
+from zitadel_client.exceptions import OpenApiError
+
+
+@pytest.fixture(scope="module")
+def base_url() -> str:
+    """Provides the base URL for tests, skipping if unset."""
+    url = os.getenv("BASE_URL")
+    if not url:
+        pytest.skip("Environment variable BASE_URL must be set", allow_module_level=True)
+    return url
+
+
+@pytest.fixture(scope="module")
+def auth_token() -> str:
+    """Provides the auth token for tests, skipping if unset."""
+    url = os.getenv("AUTH_TOKEN")
+    if not url:
+        pytest.skip("Environment variable AUTH_TOKEN must be set", allow_module_level=True)
+    return url
+
+
+class TestUseAccessTokenSpec:
+    """
+    SettingsService Integration Tests (Personal Access Token)
+
+    This suite verifies the Zitadel SettingsService API's general settings
+    endpoint works when authenticating via a Personal Access Token:
+
+     1. Retrieve general settings successfully with a valid token
+     2. Expect an ApiException when using an invalid token
+
+    Each test instantiates a new client to ensure a clean, stateless call.
+    """
+
+    def test_retrieves_general_settings_with_valid_token(
+        self,
+        base_url: str,
+        auth_token: str,
+    ) -> None:
+        """Retrieves general settings successfully with a valid access token."""
+        client = zitadel.Zitadel.with_access_token(
+            base_url,
+            auth_token,
+        )
+        client.settings.settings_service_get_general_settings()
+
+    def test_raises_api_exception_with_invalid_token(
+        self,
+        base_url: str,
+    ) -> None:
+        """Raises ApiException when using an invalid access token."""
+        client = zitadel.Zitadel.with_access_token(
+            base_url,
+            "invalid",
+        )
+        with pytest.raises(OpenApiError):
+            client.settings.settings_service_get_general_settings()

spec/auth/using_client_credentials_spec.py

@@ -0,0 +1,74 @@
+import os
+
+import pytest
+
+import zitadel_client as zitadel
+from zitadel_client.exceptions import OpenApiError
+
+
+@pytest.fixture(scope="module")
+def base_url() -> str:
+    """Provides the base URL for tests, skipping if unset."""
+    url = os.getenv("BASE_URL")
+    if not url:
+        pytest.skip("Environment variable BASE_URL must be set", allow_module_level=True)
+    return url
+
+
+@pytest.fixture(scope="module")
+def client_id() -> str:
+    """Provides the client ID for tests, skipping if unset."""
+    cid = os.getenv("CLIENT_ID")
+    if not cid:
+        pytest.skip("Environment variable CLIENT_ID must be set", allow_module_level=True)
+    return cid
+
+
+@pytest.fixture(scope="module")
+def client_secret() -> str:
+    """Provides the client secret for tests, skipping if unset."""
+    cs = os.getenv("CLIENT_SECRET")
+    if not cs:
+        pytest.skip("Environment variable CLIENT_SECRET must be set", allow_module_level=True)
+    return cs
+
+
+class TestUseClientCredentialsSpec:
+    """
+    SettingsService Integration Tests (Client Credentials)
+
+    This suite verifies the Zitadel SettingsService API's general settings
+    endpoint works when authenticating via Client Credentials:
+
+     1. Retrieve general settings successfully with valid credentials
+     2. Expect an ApiException when using invalid credentials
+
+    Each test instantiates a new client to ensure a clean, stateless call.
+    """
+
+    def test_retrieves_general_settings_with_valid_client_credentials(
+        self,
+        base_url: str,
+        client_id: str,
+        client_secret: str,
+    ) -> None:
+        """Retrieves general settings successfully with valid client credentials."""
+        client = zitadel.Zitadel.with_client_credentials(
+            base_url,
+            client_id,
+            client_secret,
+        )
+        client.settings.settings_service_get_general_settings()
+
+    def test_raises_api_exception_with_invalid_client_credentials(
+        self,
+        base_url: str,
+    ) -> None:
+        """Raises ApiException when using invalid client credentials."""
+        client = zitadel.Zitadel.with_client_credentials(
+            base_url,
+            "invalid",
+            "invalid",
+        )
+        with pytest.raises(OpenApiError):
+            client.settings.settings_service_get_general_settings()

spec/auth/using_private_key_spec.py

@@ -0,0 +1,62 @@
+import os
+import pathlib
+
+import pytest
+
+import zitadel_client as zitadel
+from zitadel_client import OpenApiError
+
+
+@pytest.fixture(scope="module")
+def base_url() -> str:
+    """Provides the base URL for tests, skipping if unset."""
+    url = os.getenv("BASE_URL")
+    if not url:
+        pytest.skip("Environment variable BASE_URL must be set", allow_module_level=True)
+    return url
+
+
+@pytest.fixture
+def key_file(tmp_path: pathlib.Path) -> str:
+    raw: str = os.getenv("JWT_KEY") or ""
+    file_path: pathlib.Path = tmp_path / "jwt.json"
+    file_path.write_text(raw)
+    return str(file_path)
+
+
+class TestUsePrivateKeySpec:
+    """
+    SettingsService Integration Tests (Private Key Assertion)
+
+    This suite verifies the Zitadel SettingsService API's general settings
+    endpoint works when authenticating via a private key assertion:
+
+     1. Retrieve general settings successfully with a valid private key
+     2. Expect an ApiException when using an invalid private key path
+
+    Each test instantiates a new client to ensure a clean, stateless call.
+    """
+
+    def test_retrieves_general_settings_with_valid_private_key(
+        self,
+        base_url: str,
+        key_file: str,
+    ) -> None:
+        """Retrieves general settings successfully with a valid private key."""
+        client = zitadel.Zitadel.with_private_key(
+            base_url,
+            key_file,
+        )
+        client.settings.settings_service_get_general_settings()
+
+    def test_raises_api_exception_with_invalid_private_key(
+        self,
+        key_file: str,
+    ) -> None:
+        """Raises ApiException when using an invalid private key path."""
+        client = zitadel.Zitadel.with_private_key(
+            "https://zitadel.cloud",
+            key_file,
+        )
+        with pytest.raises(OpenApiError):
+            client.settings.settings_service_get_general_settings()

spec/check_session_service_spec.py

@@ -0,0 +1,130 @@
+import os
+import uuid
+from typing import Generator
+
+import pytest
+
+import zitadel_client as zitadel
+from zitadel_client.exceptions import ApiException
+from zitadel_client.models import (
+    SessionServiceChecks,
+    SessionServiceCheckUser,
+    SessionServiceCreateSessionRequest,
+    SessionServiceCreateSessionResponse,
+    SessionServiceDeleteSessionBody,
+    SessionServiceGetSessionResponse,
+    SessionServiceListSessionsRequest,
+    SessionServiceListSessionsResponse,
+    SessionServiceSetSessionRequest,
+    SessionServiceSetSessionResponse,
+)
+
+
+@pytest.fixture(scope="module")
+def base_url() -> str:
+    """Provides the base URL for tests, skipping if unset."""
+    url = os.getenv("BASE_URL")
+    if not url:
+        pytest.skip("Environment variable BASE_URL must be set", allow_module_level=True)
+    return url
+
+
+@pytest.fixture(scope="module")
+def auth_token() -> str:
+    """Provides a valid personal access token, skipping if unset."""
+    token = os.getenv("AUTH_TOKEN")
+    if not token:
+        pytest.skip("Environment variable AUTH_TOKEN must be set", allow_module_level=True)
+    return token
+
+
+@pytest.fixture(scope="module")
+def client(base_url: str, auth_token: str) -> zitadel.Zitadel:
+    """Provides a Zitadel client configured with a personal access token."""
+    return zitadel.Zitadel.with_access_token(base_url, auth_token)
+
+
+@pytest.fixture
+def session(client: zitadel.Zitadel) -> Generator[SessionServiceCreateSessionResponse, None, None]:
+    """Creates a fresh session for each test and cleans up afterward."""
+    request = SessionServiceCreateSessionRequest(
+        checks=SessionServiceChecks(user=SessionServiceCheckUser(loginName="johndoe")),
+        lifetime="18000s",
+    )
+    response = client.sessions.session_service_create_session(request)
+    yield response
+    # Teardown
+    delete_body = SessionServiceDeleteSessionBody()
+    try:
+        client.sessions.session_service_delete_session(
+            response.session_id if response.session_id is not None else "",
+            delete_body,
+        )
+    except ApiException:
+        pass
+
+
+class TestSessionServiceSanityCheckSpec:
+    """
+    SessionService Integration Tests
+
+    This suite verifies the Zitadel SessionService API's basic operations using a
+    personal access token:
+
+     1. Create a session with specified checks and lifetime
+     2. Retrieve the session by ID
+     3. List sessions and ensure the created session appears
+     4. Update the session's lifetime and confirm a new token is returned
+     5. Error when retrieving a non-existent session
+
+    Each test runs in isolation: a new session is created in the `session` fixture and
+    deleted after the test to ensure a clean state.
+    """
+
+    def test_retrieves_session_details_by_id(
+        self,
+        client: zitadel.Zitadel,
+        session: SessionServiceCreateSessionResponse,
+    ) -> None:
+        """Retrieves the session details by ID."""
+        response: SessionServiceGetSessionResponse = client.sessions.session_service_get_session(
+            session.session_id if session.session_id is not None else ""
+        )
+        assert response.session is not None
+        assert response.session.id == session.session_id
+
+    def test_includes_created_session_when_listing(
+        self,
+        client: zitadel.Zitadel,
+        session: SessionServiceCreateSessionResponse,
+    ) -> None:
+        """Includes the created session when listing all sessions."""
+        request = SessionServiceListSessionsRequest(queries=[])
+        response: SessionServiceListSessionsResponse = client.sessions.session_service_list_sessions(request)
+        assert response.sessions is not None
+        assert session.session_id in [session.id for session in response.sessions]
+
+    def test_updates_session_lifetime_and_returns_new_token(
+        self,
+        client: zitadel.Zitadel,
+        session: SessionServiceCreateSessionResponse,
+    ) -> None:
+        """Updates the session lifetime and returns a new token."""
+        request = SessionServiceSetSessionRequest(lifetime="36000s")
+        response: SessionServiceSetSessionResponse = client.sessions.session_service_set_session(
+            session.session_id if session.session_id is not None else "",
+            request,
+        )
+        assert isinstance(response.session_token, str)
+
+    def test_raises_api_exception_for_nonexistent_session(
+        self,
+        client: zitadel.Zitadel,
+        session: SessionServiceCreateSessionResponse,
+    ) -> None:
+        """Raises an ApiException when retrieving a non-existent session."""
+        with pytest.raises(ApiException):
+            client.sessions.session_service_get_session(
+                str(uuid.uuid4()),
+                session_token=session.session_token,
+            )