Add support for test user (#163)

Author: dorsha

README.md

@@ -422,7 +422,7 @@ You can create, update, delete or load tenants:
 # You can optionally set your own ID when creating a tenant
 descope_client.mgmt.tenant.create(
     name="My First Tenant",
-    id="my-custom-id", # This is optional. If omitted
+    id="my-custom-id", # This is optional.
     self_provisioning_domains=["domain.com"],
 )
 
@@ -699,6 +699,55 @@ updated_jwt = descope_client.mgmt.jwt.update_jwt(
 )
 ```
 
+### Utils for your end to end (e2e) tests and integration tests
+
+To ease your e2e tests, we exposed dedicated management methods,
+that way, you don't need to use 3rd party messaging services in order to receive sign-in/up Emails or SMS, and avoid the need of parsing the code and token from them.
+
+```Python
+# User for test can be created, this user will be able to generate code/link without
+# the need of 3rd party messaging services.
+# Test user must have a loginId, other fields are optional.
+# Roles should be set directly if no tenants exist, otherwise set
+# on a per-tenant basis.
+descope_client.mgmt.user.create_test_user(
+    login_id="[email protected]",
+    email="[email protected]",
+    display_name="Desmond Copeland",
+    user_tenants=[
+        AssociatedTenant("my-tenant-id", ["role-name1"]),
+    ],
+)
+
+# Now test user got created, and this user will be available until you delete it,
+# you can use any management operation for test user CRUD.
+# You can also delete all test users.
+descope_client.mgmt.user.delete_all_test_users()
+
+# OTP code can be generated for test user, for example:
+resp = descope_client.mgmt.user.generate_otp_for_test_user(
+    DeliveryMethod.EMAIL, "login-id"
+)
+code = resp["code"]
+# Now you can verify the code is valid (using descope_client.*.verify for example)
+
+# Same as OTP, magic link can be generated for test user, for example:
+resp = descope_client.mgmt.user.generate_magic_link_for_test_user(
+    DeliveryMethod.EMAIL, "login-id", ""
+)
+link = resp["link"]
+
+# Enchanted link can be generated for test user, for example:
+resp = descope_client.mgmt.user.generate_enchanted_link_for_test_user(
+    "login-id", ""
+)
+link = resp["link"]
+pending_ref = resp["pendingRef"]
+
+# Note 1: The generate code/link functions, work only for test users, will not work for regular users.
+# Note 2: In case of testing sign-in / sign-up operations with test users, need to make sure to generate the code prior calling the sign-in / sign-up operations.
+```
+
 ## API Rate limits
 
 Handle API rate limits by comparing the exception to the APIRateLimitExceeded exception, which includes the RateLimitParameters map with the key "Retry-After." This key indicates how many seconds until the next valid API call can take place. More information on Descope's rate limit is covered here: [Descope rate limit reference page](https://docs.descope.com/rate-limit)

descope/auth.py

@@ -213,6 +213,19 @@ def get_login_id_by_method(method: DeliveryMethod, user: dict) -> Tuple[str, str
                 400, ERROR_TYPE_INVALID_ARGUMENT, f"Unknown delivery method: {method}"
             )
 
+    @staticmethod
+    def get_method_string(method: DeliveryMethod) -> str:
+        if method is DeliveryMethod.EMAIL:
+            return "email"
+        elif method is DeliveryMethod.SMS:
+            return "phone"
+        elif method is DeliveryMethod.WHATSAPP:
+            return "whatsapp"
+        else:
+            raise AuthException(
+                400, ERROR_TYPE_INVALID_ARGUMENT, f"Unknown delivery method: {method}"
+            )
+
     @staticmethod
     def validate_email(email: str):
         if email == "":
@@ -309,7 +322,6 @@ def _validate_and_load_public_key(public_key) -> Tuple[str, jwt.PyJWK, str]:
             )
 
     def _fetch_public_keys(self) -> None:
-
         # This function called under mutex protection so no need to acquire it once again
         response = requests.get(
             f"{self.base_url}{EndpointsV2.public_key_path}/{self.project_id}",

descope/management/common.py

@@ -12,6 +12,7 @@ class MgmtV1:
     user_create_path = "/v1/mgmt/user/create"
     user_update_path = "/v1/mgmt/user/update"
     user_delete_path = "/v1/mgmt/user/delete"
+    user_delete_all_test_users_path = "/v1/mgmt/user/test/delete/all"
     user_load_path = "/v1/mgmt/user"
     users_search_path = "/v1/mgmt/user/search"
     user_update_status_path = "/v1/mgmt/user/update/status"
@@ -22,6 +23,9 @@ class MgmtV1:
     user_remove_role_path = "/v1/mgmt/user/update/role/remove"
     user_add_tenant_path = "/v1/mgmt/user/update/tenant/add"
     user_remove_tenant_path = "/v1/mgmt/user/update/tenant/remove"
+    user_generate_otp_for_test_path = "/v1/mgmt/tests/generate/otp"
+    user_generate_magic_link_for_test_path = "/v1/mgmt/tests/generate/magiclink"
+    user_generate_enchanted_link_for_test_path = "/v1/mgmt/tests/generate/enchantedlink"
 
     # access key
     access_key_create_path = "/v1/mgmt/accesskey/create"

descope/management/user.py

@@ -1,6 +1,7 @@
 from typing import List
 
 from descope.auth import Auth
+from descope.common import DeliveryMethod
 from descope.exceptions import ERROR_TYPE_INVALID_ARGUMENT, AuthException
 from descope.management.common import (
     AssociatedTenant,
@@ -48,7 +49,62 @@ def create(
         response = self._auth.do_post(
             MgmtV1.user_create_path,
             User._compose_create_body(
-                login_id, email, phone, display_name, role_names, user_tenants, False
+                login_id,
+                email,
+                phone,
+                display_name,
+                role_names,
+                user_tenants,
+                False,
+                False,
+            ),
+            pswd=self._auth.management_key,
+        )
+        return response.json()
+
+    def create_test_user(
+        self,
+        login_id: str,
+        email: str = None,
+        phone: str = None,
+        display_name: str = None,
+        role_names: List[str] = [],
+        user_tenants: List[AssociatedTenant] = [],
+    ) -> dict:
+        """
+        Create a new test user.
+        The login_id is required and will determine what the user will use to sign in.
+        Make sure the login id is unique for test. All other fields are optional.
+
+        Args:
+        login_id (str): user login ID.
+        email (str): Optional user email address.
+        phone (str): Optional user phone number.
+        display_name (str): Optional user display name.
+        role_names (List[str]): An optional list of the user's roles without tenant association. These roles are
+            mutually exclusive with the `user_tenant` roles.
+        user_tenants (List[AssociatedTenant]): An optional list of the user's tenants, and optionally, their roles per tenant. These roles are
+            mutually exclusive with the general `role_names`.
+
+        Return value (dict):
+        Return dict in the format
+             {"user": {}}
+        Containing the created test user information.
+
+        Raise:
+        AuthException: raised if update operation fails
+        """
+        response = self._auth.do_post(
+            MgmtV1.user_create_path,
+            User._compose_create_body(
+                login_id,
+                email,
+                phone,
+                display_name,
+                role_names,
+                user_tenants,
+                False,
+                True,
             ),
             pswd=self._auth.management_key,
         )
@@ -77,7 +133,14 @@ def invite(
         response = self._auth.do_post(
             MgmtV1.user_create_path,
             User._compose_create_body(
-                login_id, email, phone, display_name, role_names, user_tenants, True
+                login_id,
+                email,
+                phone,
+                display_name,
+                role_names,
+                user_tenants,
+                True,
+                False,
             ),
             pswd=self._auth.management_key,
         )
@@ -112,7 +175,7 @@ def update(
         self._auth.do_post(
             MgmtV1.user_update_path,
             User._compose_update_body(
-                login_id, email, phone, display_name, role_names, user_tenants
+                login_id, email, phone, display_name, role_names, user_tenants, False
             ),
             pswd=self._auth.management_key,
         )
@@ -136,6 +199,21 @@ def delete(
             pswd=self._auth.management_key,
         )
 
+    def delete_all_test_users(
+        self,
+    ):
+        """
+        Delete all test users in the project. IMPORTANT: This action is irreversible. Use carefully.
+
+        Raise:
+        AuthException: raised if creation operation fails
+        """
+        self._auth.do_post(
+            MgmtV1.user_delete_all_test_users_path,
+            {},
+            pswd=self._auth.management_key,
+        )
+
     def load(
         self,
         login_id: str,
@@ -193,6 +271,8 @@ def search_all(
         role_names: List[str] = [],
         limit: int = 0,
         page: int = 0,
+        test_users_only: bool = False,
+        with_test_user: bool = False,
     ) -> dict:
         """
         Search all users.
@@ -202,6 +282,8 @@ def search_all(
         role_names (List[str]): Optional list of role names to filter by
         limit (int): Optional limit of the number of users returned. Leave empty for default.
         page (int): Optional pagination control. Pages start at 0 and must be non-negative.
+        test_users_only (bool): Optional filter only test users.
+        with_test_user (bool): Optional include test users in search.
 
         Return value (dict):
         Return dict in the format
@@ -228,6 +310,8 @@ def search_all(
                 "roleNames": role_names,
                 "limit": limit,
                 "page": page,
+                "testUsersOnly": test_users_only,
+                "withTestUser": with_test_user,
             },
             pswd=self._auth.management_key,
         )
@@ -536,6 +620,98 @@ def remove_tenant_roles(
         )
         return response.json()
 
+    def generate_otp_for_test_user(
+        self,
+        method: DeliveryMethod,
+        login_id: str,
+    ) -> dict:
+        """
+        Generate OTP for the given login ID of a test user.
+        This is useful when running tests and don't want to use 3rd party messaging services.
+
+        Args:
+        method (DeliveryMethod): The method to use for "delivering" the OTP verification code to the user, for example
+            EMAIL, SMS, or WHATSAPP
+        login_id (str): The login ID of the test user being validated.
+
+        Return value (dict):
+        Return dict in the format
+             {"code": "", "loginId": ""}
+        Containing the code for the login (exactly as it sent via Email or SMS).
+
+        Raise:
+        AuthException: raised if the operation fails
+        """
+        response = self._auth.do_post(
+            MgmtV1.user_generate_otp_for_test_path,
+            {"loginId": login_id, "deliveryMethod": Auth.get_method_string(method)},
+            pswd=self._auth.management_key,
+        )
+        return response.json()
+
+    def generate_magic_link_for_test_user(
+        self,
+        method: DeliveryMethod,
+        login_id: str,
+        uri: str,
+    ) -> dict:
+        """
+        Generate Magic Link for the given login ID of a test user.
+        This is useful when running tests and don't want to use 3rd party messaging services.
+
+        Args:
+        method (DeliveryMethod): The method to use for "delivering" the verification magic link to the user, for example
+            EMAIL, SMS, or WHATSAPP
+        login_id (str): The login ID of the test user being validated.
+        uri (str): Optional redirect uri which will be used instead of any global configuration.
+
+        Return value (dict):
+        Return dict in the format
+             {"link": "", "loginId": ""}
+        Containing the magic link for the login (exactly as it sent via Email or SMS).
+
+        Raise:
+        AuthException: raised if the operation fails
+        """
+        response = self._auth.do_post(
+            MgmtV1.user_generate_magic_link_for_test_path,
+            {
+                "loginId": login_id,
+                "deliveryMethod": Auth.get_method_string(method),
+                "URI": uri,
+            },
+            pswd=self._auth.management_key,
+        )
+        return response.json()
+
+    def generate_enchanted_link_for_test_user(
+        self,
+        login_id: str,
+        uri: str,
+    ) -> dict:
+        """
+        Generate Enchanted Link for the given login ID of a test user.
+        This is useful when running tests and don't want to use 3rd party messaging services.
+
+        Args:
+        login_id (str): The login ID of the test user being validated.
+        uri (str): Optional redirect uri which will be used instead of any global configuration.
+
+        Return value (dict):
+        Return dict in the format
+             {"link": "", "loginId": "", "pendingRef": ""}
+        Containing the enchanted link for the login (exactly as it sent via Email or SMS) and pendingRef.
+
+        Raise:
+        AuthException: raised if the operation fails
+        """
+        response = self._auth.do_post(
+            MgmtV1.user_generate_enchanted_link_for_test_path,
+            {"loginId": login_id, "URI": uri},
+            pswd=self._auth.management_key,
+        )
+        return response.json()
+
     @staticmethod
     def _compose_create_body(
         login_id: str,
@@ -545,9 +721,10 @@ def _compose_create_body(
         role_names: List[str],
         user_tenants: List[AssociatedTenant],
         invite: bool,
+        test: bool,
     ) -> dict:
         body = User._compose_update_body(
-            login_id, email, phone, display_name, role_names, user_tenants
+            login_id, email, phone, display_name, role_names, user_tenants, test
         )
         body["invite"] = invite
         return body
@@ -560,6 +737,7 @@ def _compose_update_body(
         display_name: str,
         role_names: List[str],
         user_tenants: List[AssociatedTenant],
+        test: bool,
     ) -> dict:
         return {
             "loginId": login_id,
@@ -568,4 +746,5 @@ def _compose_update_body(
             "displayName": display_name,
             "roleNames": role_names,
             "userTenants": associated_tenants_to_dict(user_tenants),
+            "test": test,
         }