pytest-clerk-mock 0.0.2__py3-none-any.whl

pytest_clerk_mock/__init__.py

@@ -0,0 +1,39 @@
+from pytest_clerk_mock.client import MockClerkClient
+from pytest_clerk_mock.helpers import (
+    mock_clerk_user_creation,
+    mock_clerk_user_creation_failure,
+    mock_clerk_user_exists,
+)
+from pytest_clerk_mock.models.auth import MockAuthResult, MockClerkUser
+from pytest_clerk_mock.models.organization import (
+    MockOrganization,
+    MockOrganizationMembership,
+    MockOrganizationMembershipsResponse,
+)
+from pytest_clerk_mock.models.user import MockEmailAddress, MockPhoneNumber, MockUser
+from pytest_clerk_mock.plugin import (
+    create_mock_clerk_fixture,
+    mock_clerk,
+    mock_clerk_backend,
+)
+from pytest_clerk_mock.services.users import MockListResponse, UserNotFoundError
+
+__all__ = [
+    "create_mock_clerk_fixture",
+    "mock_clerk",
+    "mock_clerk_backend",
+    "mock_clerk_user_creation",
+    "mock_clerk_user_creation_failure",
+    "mock_clerk_user_exists",
+    "MockAuthResult",
+    "MockClerkClient",
+    "MockClerkUser",
+    "MockEmailAddress",
+    "MockListResponse",
+    "MockOrganization",
+    "MockOrganizationMembership",
+    "MockOrganizationMembershipsResponse",
+    "MockPhoneNumber",
+    "MockUser",
+    "UserNotFoundError",
+]

pytest_clerk_mock/client.py

@@ -0,0 +1,189 @@
+from contextlib import contextmanager
+from typing import Any, Generator
+
+from pytest_clerk_mock.models.auth import MockAuthResult, MockClerkUser
+from pytest_clerk_mock.models.organization import (
+    MockOrganization,
+    MockOrganizationMembership,
+    MockOrganizationMembershipsResponse,
+)
+from pytest_clerk_mock.services.auth import MockAuthState
+from pytest_clerk_mock.services.users import MockUsersClient
+
+
+class MockClerkClient:
+    """Mock implementation of Clerk's SDK client."""
+
+    def __init__(
+        self,
+        default_user_id: str | None = "user_test_owner",
+        default_org_id: str | None = "org_test_123",
+        default_org_role: str = "org:admin",
+    ) -> None:
+        self._users = MockUsersClient()
+        self._auth_state = MockAuthState()
+        self._memberships: dict[str, list[MockOrganizationMembership]] = {}
+
+        if default_user_id is not None:
+            self._auth_state.configure(default_user_id, default_org_id, default_org_role)
+
+    @property
+    def users(self) -> MockUsersClient:
+        """Access the Users API."""
+
+        return self._users
+
+    def reset(self) -> None:
+        """Reset all mock services."""
+
+        self._users.reset()
+        self._auth_state.reset()
+        self._memberships.clear()
+
+    def authenticate_request(
+        self,
+        request: Any,
+        options: Any = None,
+    ) -> MockAuthResult:
+        """Mock implementation of Clerk's authenticate_request.
+
+        Args:
+            request: The FastAPI/Starlette request object (ignored in mock)
+            options: AuthenticateRequestOptions (ignored in mock)
+
+        Returns:
+            MockAuthResult with current auth state
+        """
+
+        return self._auth_state.get_result()
+
+    def configure_auth(
+        self,
+        user_id: str | None,
+        org_id: str | None = None,
+        org_role: str = "org:admin",
+    ) -> None:
+        """Configure the authentication state.
+
+        Args:
+            user_id: The user ID to return in auth results (None for unauthenticated)
+            org_id: The organization ID for the authenticated user
+            org_role: The role of the user in the organization
+        """
+
+        self._auth_state.configure(user_id, org_id, org_role)
+
+    def configure_auth_from_user(
+        self,
+        user: MockClerkUser,
+        org_id: str | None = None,
+        org_role: str = "org:admin",
+    ) -> None:
+        """Configure auth state using a predefined MockClerkUser.
+
+        Args:
+            user: The MockClerkUser enum value
+            org_id: The organization ID for the authenticated user
+            org_role: The role of the user in the organization
+        """
+
+        self._auth_state.configure(user.value, org_id, org_role)
+
+    @contextmanager
+    def as_user(
+        self,
+        user_id: str | None,
+        org_id: str | None = None,
+        org_role: str = "org:admin",
+    ) -> Generator[None, None, None]:
+        """Context manager to temporarily switch to a different user.
+
+        Args:
+            user_id: The user ID to use within the context
+            org_id: The organization ID for the user
+            org_role: The role of the user in the organization
+
+        Yields:
+            None
+
+        Example:
+            with mock_clerk.as_user("user_123", org_id="org_456"):
+                # Requests will be authenticated as user_123
+                pass
+        """
+
+        previous = self._auth_state.snapshot()
+        self._auth_state.configure(user_id, org_id, org_role)
+
+        try:
+            yield
+        finally:
+            self._auth_state.restore(previous)
+
+    @contextmanager
+    def as_clerk_user(
+        self,
+        user: MockClerkUser,
+        org_id: str | None = None,
+        org_role: str = "org:admin",
+    ) -> Generator[None, None, None]:
+        """Context manager using predefined MockClerkUser.
+
+        Args:
+            user: The MockClerkUser enum value
+            org_id: The organization ID for the user
+            org_role: The role of the user in the organization
+
+        Example:
+            with mock_clerk.as_clerk_user(MockClerkUser.TEAM_OWNER, org_id="org_123"):
+                # Requests will be authenticated as team owner
+                pass
+        """
+
+        with self.as_user(user.value, org_id, org_role):
+            yield
+
+    def add_organization_membership(
+        self,
+        user_id: str,
+        org_id: str,
+        role: str = "org:member",
+        org_name: str = "",
+    ) -> MockOrganizationMembership:
+        """Add an organization membership for a user.
+
+        Args:
+            user_id: The user ID to add membership for
+            org_id: The organization ID
+            role: The role in the organization
+            org_name: Optional organization name
+
+        Returns:
+            The created membership
+        """
+
+        membership = MockOrganizationMembership(
+            id=f"orgmem_{user_id}_{org_id}",
+            role=role,
+            organization=MockOrganization(id=org_id, name=org_name),
+        )
+
+        if user_id not in self._memberships:
+            self._memberships[user_id] = []
+
+        self._memberships[user_id].append(membership)
+
+        return membership
+
+    async def _get_organization_memberships_async(
+        self,
+        user_id: str,
+    ) -> MockOrganizationMembershipsResponse:
+        """Get organization memberships for a user (internal async method)."""
+
+        memberships = self._memberships.get(user_id, [])
+
+        return MockOrganizationMembershipsResponse(
+            data=memberships,
+            total_count=len(memberships),
+        )

pytest_clerk_mock/helpers.py

@@ -0,0 +1,148 @@
+from contextlib import contextmanager
+from typing import Generator
+from unittest.mock import MagicMock, patch
+
+import httpx
+from clerk_backend_api import SDKError
+from clerk_backend_api.models import ClerkErrors
+from clerk_backend_api.models.clerkerror import ClerkError
+from clerk_backend_api.models.clerkerrors import ClerkErrorsData
+from pydantic import BaseModel
+
+EMAIL_EXISTS_ERROR_CODE = "form_identifier_exists"
+
+
+class MockClerkUserResponse(BaseModel):
+    """Simple mock Clerk user returned from create_async."""
+
+    id: str
+
+
+class MockClerkUserListResponse:
+    """Mock response from Clerk users.list_async."""
+
+    def __init__(self, data: list[MockClerkUserResponse]):
+        self.data = data
+
+
+@contextmanager
+def mock_clerk_user_creation(
+    patch_target: str,
+    clerk_user_id: str = "user_clerk_mock_123",
+) -> Generator[MagicMock, None, None]:
+    """Mock Clerk user creation API.
+
+    Args:
+        patch_target: The module path to patch.
+        clerk_user_id: The ID to return for the created user.
+
+    Yields:
+        The mock object for assertions.
+
+    Example:
+        with mock_clerk_user_creation("api.core.clerk.clerk.users.create_async", "user_123") as mock:
+            # Your test code here
+            mock.assert_called_once()
+    """
+
+    with patch(patch_target) as mock_create:
+        mock_create.return_value = MockClerkUserResponse(id=clerk_user_id)
+        yield mock_create
+
+
+@contextmanager
+def mock_clerk_user_creation_failure(
+    patch_target: str,
+    error_message: str = "Clerk API error",
+) -> Generator[MagicMock, None, None]:
+    """Mock Clerk user creation API to simulate a failure.
+
+    Args:
+        patch_target: The module path to patch.
+        error_message: The error message to include.
+
+    Yields:
+        The mock object for assertions.
+
+    Example:
+        with mock_clerk_user_creation_failure("api.core.clerk.clerk.users.create_async") as mock:
+            with pytest.raises(ErrorResponse):
+                # Your test code here
+    """
+
+    mock_response = MagicMock()
+    mock_response.status_code = 500
+    mock_response.text = error_message
+    mock_response.headers = {}
+
+    with patch(patch_target) as mock_create:
+        mock_create.side_effect = SDKError(error_message, mock_response)
+        yield mock_create
+
+
+@contextmanager
+def mock_clerk_user_exists(
+    create_patch_target: str,
+    list_patch_target: str,
+    existing_clerk_user_id: str = "user_clerk_existing_123",
+) -> Generator[tuple[MagicMock, MagicMock], None, None]:
+    """Mock Clerk user creation to simulate an email already exists scenario.
+
+    This simulates the case where create_async fails because the email is taken,
+    but list_async returns the existing user so we can link it.
+
+    Args:
+        create_patch_target: The module path to patch for create_async.
+        list_patch_target: The module path to patch for list_async.
+        existing_clerk_user_id: The ID of the existing Clerk user to return.
+
+    Yields:
+        A tuple of (mock_create, mock_list) for assertions.
+
+    Example:
+        with mock_clerk_user_exists(
+            "api.core.clerk.clerk.users.create_async",
+            "api.core.clerk.clerk.users.list_async",
+            "user_existing_123"
+        ) as (mock_create, mock_list):
+            # Your test code here
+            mock_create.assert_called_once()
+            mock_list.assert_called_once()
+    """
+
+    mock_response = httpx.Response(
+        status_code=422,
+        json={
+            "errors": [
+                {
+                    "message": "That email address is taken. Please try another.",
+                    "long_message": "That email address is taken. Please try another.",
+                    "code": EMAIL_EXISTS_ERROR_CODE,
+                }
+            ]
+        },
+    )
+
+    email_exists_error = ClerkErrors(
+        data=ClerkErrorsData(
+            errors=[
+                ClerkError(
+                    message="That email address is taken. Please try another.",
+                    long_message="That email address is taken. Please try another.",
+                    code=EMAIL_EXISTS_ERROR_CODE,
+                )
+            ]
+        ),
+        raw_response=mock_response,
+    )
+
+    with (
+        patch(create_patch_target) as mock_create,
+        patch(list_patch_target) as mock_list,
+    ):
+        mock_create.side_effect = email_exists_error
+        mock_list.return_value = MockClerkUserListResponse(
+            data=[MockClerkUserResponse(id=existing_clerk_user_id)]
+        )
+        yield mock_create, mock_list
+

pytest_clerk_mock/models/__init__.py

@@ -0,0 +1,18 @@
+from pytest_clerk_mock.models.auth import MockAuthResult, MockClerkUser
+from pytest_clerk_mock.models.organization import (
+    MockOrganization,
+    MockOrganizationMembership,
+    MockOrganizationMembershipsResponse,
+)
+from pytest_clerk_mock.models.user import MockEmailAddress, MockPhoneNumber, MockUser
+
+__all__ = [
+    "MockAuthResult",
+    "MockClerkUser",
+    "MockEmailAddress",
+    "MockOrganization",
+    "MockOrganizationMembership",
+    "MockOrganizationMembershipsResponse",
+    "MockPhoneNumber",
+    "MockUser",
+]

pytest_clerk_mock/models/auth.py

@@ -0,0 +1,50 @@
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MockClerkUser(Enum):
+    """Predefined user types for common test scenarios."""
+
+    TEAM_OWNER = "user_test_owner"
+    TEAM_MEMBER = "user_test_member"
+    GUEST = "user_test_guest"
+    UNAUTHENTICATED = None
+
+
+class MockAuthResult(BaseModel):
+    """Mock result from Clerk authenticate_request."""
+
+    is_signed_in: bool = False
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Alias for is_signed_in."""
+
+        return self.is_signed_in
+
+    @classmethod
+    def signed_in(
+        cls,
+        user_id: str,
+        org_id: str | None = None,
+        org_role: str = "org:admin",
+    ) -> "MockAuthResult":
+        """Create a signed-in auth result."""
+
+        return cls(
+            is_signed_in=True,
+            payload={
+                "sub": user_id,
+                "org_id": org_id,
+                "org_role": org_role,
+            },
+        )
+
+    @classmethod
+    def signed_out(cls) -> "MockAuthResult":
+        """Create a signed-out auth result."""
+
+        return cls(is_signed_in=False, payload={})

pytest_clerk_mock/models/organization.py

@@ -0,0 +1,30 @@
+from pydantic import BaseModel, Field
+
+
+class MockOrganization(BaseModel):
+    """Represents a Clerk Organization."""
+
+    id: str
+    name: str = ""
+    slug: str = ""
+    created_at: int = 0
+    updated_at: int = 0
+
+
+class MockOrganizationMembership(BaseModel):
+    """Represents a user's membership in an organization."""
+
+    id: str
+    role: str = "org:member"
+    organization: MockOrganization | None = None
+    public_user_data: dict | None = None
+    created_at: int = 0
+    updated_at: int = 0
+
+
+class MockOrganizationMembershipsResponse(BaseModel):
+    """Response from get_organization_memberships_async."""
+
+    data: list[MockOrganizationMembership] = Field(default_factory=list)
+    total_count: int = 0
+

pytest_clerk_mock/models/user.py

@@ -0,0 +1,92 @@
+from datetime import datetime
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MockEmailAddress(BaseModel):
+    """Represents a Clerk email address object."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    email_address: str
+    verification: dict | None = None
+    linked_to: list[dict] = Field(default_factory=list)
+
+    @classmethod
+    def create(cls, email: str, email_id: str) -> Self:
+        """Create a verified email address."""
+
+        return cls(
+            id=email_id,
+            email_address=email,
+            verification={"status": "verified", "strategy": "email_code"},
+            linked_to=[],
+        )
+
+
+class MockPhoneNumber(BaseModel):
+    """Represents a Clerk phone number object."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    phone_number: str
+    verification: dict | None = None
+    linked_to: list[dict] = Field(default_factory=list)
+
+    @classmethod
+    def create(cls, phone: str, phone_id: str) -> Self:
+        """Create a verified phone number."""
+
+        return cls(
+            id=phone_id,
+            phone_number=phone,
+            verification={"status": "verified", "strategy": "phone_code"},
+            linked_to=[],
+        )
+
+
+class MockUser(BaseModel):
+    """Represents a Clerk User object."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    external_id: str | None = None
+    primary_email_address_id: str | None = None
+    primary_phone_number_id: str | None = None
+    primary_web3_wallet_id: str | None = None
+    username: str | None = None
+    first_name: str | None = None
+    last_name: str | None = None
+    profile_image_url: str = ""
+    image_url: str = ""
+    has_image: bool = False
+    public_metadata: dict = Field(default_factory=dict)
+    private_metadata: dict = Field(default_factory=dict)
+    unsafe_metadata: dict = Field(default_factory=dict)
+    email_addresses: list[MockEmailAddress] = Field(default_factory=list)
+    phone_numbers: list[MockPhoneNumber] = Field(default_factory=list)
+    web3_wallets: list[dict] = Field(default_factory=list)
+    passkeys: list[dict] = Field(default_factory=list)
+    password_enabled: bool = False
+    two_factor_enabled: bool = False
+    totp_enabled: bool = False
+    backup_code_enabled: bool = False
+    external_accounts: list[dict] = Field(default_factory=list)
+    saml_accounts: list[dict] = Field(default_factory=list)
+    last_sign_in_at: int | None = None
+    banned: bool = False
+    locked: bool = False
+    lockout_expires_in_seconds: int | None = None
+    verification_attempts_remaining: int | None = None
+    created_at: int = Field(default_factory=lambda: int(datetime.now().timestamp() * 1000))
+    updated_at: int = Field(default_factory=lambda: int(datetime.now().timestamp() * 1000))
+    delete_self_enabled: bool = True
+    create_organization_enabled: bool = True
+    last_active_at: int | None = None
+    create_organizations_limit: int | None = None
+    legal_accepted_at: int | None = None
+