feat: add pagination support to get realm roles (#659)

Author: NikshetSteh

src/keycloak/keycloak_admin.py

@@ -2910,7 +2910,9 @@ def get_realm_users_profile(self) -> dict:
         )
         return raise_error_from_response(data_raw, KeycloakGetError, expected_codes=[HTTP_OK])
 
-    def get_realm_roles(self, brief_representation: bool = True, search_text: str = "") -> list:
+    def get_realm_roles(
+        self, brief_representation: bool = True, search_text: str = "", query: dict | None = None
+    ) -> list:
         """
         Get all roles for the realm or client.
 
@@ -2921,20 +2923,23 @@ def get_realm_roles(self, brief_representation: bool = True, search_text: str =
         :type brief_representation: bool
         :param search_text: optional search text to limit the returned result.
         :type search_text: str
+        :param query: Query parameters (optional)
+        :type query: dict
         :return: Keycloak server response (RoleRepresentation)
         :rtype: list
         """
+        query = query or {}
         params_path = {"realm-name": self.connection.realm_name}
         params = {"briefRepresentation": brief_representation}
+        url = urls_patterns.URL_ADMIN_REALM_ROLES.format(**params_path)
 
         if search_text is not None and search_text.strip() != "":
             params["search"] = search_text
 
-        data_raw = self.connection.raw_get(
-            urls_patterns.URL_ADMIN_REALM_ROLES.format(**params_path),
-            **params,
-        )
-        return raise_error_from_response(data_raw, KeycloakGetError)
+        if "first" in query and "max" in query:
+            return self.__fetch_paginated(url, query)
+
+        return self.__fetch_all(url, params)
 
     def get_realm_role_groups(
         self,
@@ -8176,9 +8181,7 @@ async def a_get_realm_users_profile(self) -> dict:
         return raise_error_from_response(data_raw, KeycloakGetError, expected_codes=[HTTP_OK])
 
     async def a_get_realm_roles(
-        self,
-        brief_representation: bool = True,
-        search_text: str = "",
+        self, brief_representation: bool = True, search_text: str = "", query: dict | None = None
     ) -> list:
         """
         Get all roles for the realm or client asynchronously.
@@ -8190,20 +8193,23 @@ async def a_get_realm_roles(
         :type brief_representation: bool
         :param search_text: optional search text to limit the returned result.
         :type search_text: str
+        :param query: Query parameters (optional)
+        :type query: dict
         :return: Keycloak server response (RoleRepresentation)
         :rtype: list
         """
+        query = query or {}
         params_path = {"realm-name": self.connection.realm_name}
         params = {"briefRepresentation": brief_representation}
+        url = urls_patterns.URL_ADMIN_REALM_ROLES.format(**params_path)
 
         if search_text is not None and search_text.strip() != "":
             params["search"] = search_text
 
-        data_raw = await self.connection.a_raw_get(
-            urls_patterns.URL_ADMIN_REALM_ROLES.format(**params_path),
-            **params,
-        )
-        return raise_error_from_response(data_raw, KeycloakGetError)
+        if "first" in query and "max" in query:
+            return await self.a___fetch_paginated(url, query)
+
+        return await self.a___fetch_all(url, params)
 
     async def a_get_realm_role_groups(
         self,

tests/test_keycloak_admin.py

@@ -1662,6 +1662,31 @@ def test_realm_roles(admin: KeycloakAdmin, realm: str) -> None:
     assert err.match(COULD_NOT_FIND_ROLE_REGEX)
 
 
+def test_realm_roles_pagination(admin: KeycloakAdmin, realm: str) -> None:
+    """
+    Test realm roles pagination.
+
+    :param admin: Keycloak admin
+    :type admin: KeycloakAdmin
+    :param realm: Keycloak realm
+    :type realm: str
+    """
+    admin.change_current_realm(realm)
+
+    for ind in range(admin.PAGE_SIZE + 50 - 3):
+        role_name = f"role_{ind:03}"
+        admin.create_realm_role(payload={"name": role_name})
+
+    roles = admin.get_realm_roles()
+    assert len(roles) == admin.PAGE_SIZE + 50, len(roles)
+
+    roles = admin.get_realm_roles(query={"first": 100, "max": 20})
+    assert len(roles) == 20, len(roles)
+
+    roles = admin.get_realm_roles(query={"first": 120, "max": 50})
+    assert len(roles) == 30, len(roles)
+
+
 @pytest.mark.parametrize(
     ("testcase", "arg_brief_repr", "includes_attributes"),
     [
@@ -5194,6 +5219,32 @@ async def test_a_realm_roles(admin: KeycloakAdmin, realm: str) -> None:
     assert err.match(COULD_NOT_FIND_ROLE_REGEX)
 
 
+@pytest.mark.asyncio
+async def test_a_realm_roles_pagination(admin: KeycloakAdmin, realm: str) -> None:
+    """
+    Test realm roles pagination.
+
+    :param admin: Keycloak admin
+    :type admin: KeycloakAdmin
+    :param realm: Keycloak realm
+    :type realm: str
+    """
+    admin.change_current_realm(realm)
+
+    for ind in range(admin.PAGE_SIZE + 50 - 3):
+        role_name = f"role_{ind:03}"
+        admin.create_realm_role(payload={"name": role_name})
+
+    roles = await admin.a_get_realm_roles()
+    assert len(roles) == admin.PAGE_SIZE + 50, len(roles)
+
+    roles = await admin.a_get_realm_roles(query={"first": 100, "max": 20})
+    assert len(roles) == 20, len(roles)
+
+    roles = await admin.a_get_realm_roles(query={"first": 120, "max": 50})
+    assert len(roles) == 30, len(roles)
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     ("testcase", "arg_brief_repr", "includes_attributes"),