jam.tests.clients

clients

Classes:

Name	Description
TestAsyncJam	A test async client for Jam.
TestJam	A test client for Jam.

TestAsyncJam

TestAsyncJam(
    config: Optional[Union[str, dict[str, Any]]] = None,
    pointer: str = "jam",
)

Bases: Jam

A test async client for Jam.

Example

import pytest
import pytest_asyncio
import asyncio
from jam.tests import TestAsyncJam
from jam.tests.fakers import invalid_token

@pytest_asyncio.fixture
async def client() -> TestAsyncJam:
    return TestAsyncJam()

@pytest.mark.asyncio
async def test_gen_jwt_token(client) -> None:
    payload = {"user_id": 1, "role": "admin"}
    token = await client.gen_jwt_token(payload)
    assert isinstance(token, str)
    assert token.count(".") == 2  # JWT tokens have two dots

@pytest.mark.asyncio
async def test_verify_jwt_token(client) -> None:
    payload = {"user_id": 1, "role": "admin"}
    token = await client.gen_jwt_token(payload)
    verified_payload = await client.verify_jwt_token(token, check_exp=False, check_list=False)
    assert verified_payload == payload

Parameters:

Name	Type	Description	Default
config	str | dict[str, Any] | None	Jam configuration.	None
pointer	str	Pointer for the client instance.	'jam'

Methods:

Name	Description
clear_sessions	Clear all sessions associated with a specific session key.
create_session	Create new session.
delete_session	Delete a session by its ID.
gen_jwt_token	Generate a fake JWT token for testing purposes.
get_otp_code	Generates a OTP code.
get_otp_uri	Generates an otpauth:// URI for Google Authenticator.
get_session	Retrieve session data by session ID.
jwt_create_token	Generate a fake JWT token for testing purposes.
jwt_make_payload	Payload maker tool.
jwt_verify_token	Verify JWT token.
make_payload	Payload maker tool.
oauth2_client_credentials_flow	Fake client MtM flow.
oauth2_fetch_token	Fake fetch token.
oauth2_get_authorized_url	Test oauth2 URL method.
oauth2_refresh_token	Fake refresh token.
otp_code	Generates a OTP code.
otp_uri	Generates an otpauth:// URI for Google Authenticator.
otp_verify_code	Verifies a given OTP code.
rework_session	Rework an existing session key to a new one.
session_clear	Clear all sessions associated with a specific session key.
session_create	Create new session.
session_delete	Delete a session by its ID.
session_get	Retrieve session data by session ID.
session_rework	Rework an existing session key to a new one.
session_update	Update session data by session ID.
update_session	Update session data by session ID.
verify_jwt_token	Verify JWT token.
verify_otp_code	Verifies a given OTP code.

clear_sessions async

clear_sessions(session_key: str) -> None

Clear all sessions associated with a specific session key.

Parameters:

Name	Type	Description	Default
session_key	str	The session key whose sessions are to be cleared.	required

create_session async

create_session(
    session_key: str, data: dict[str, Any]
) -> str

Create new session.

Parameters:

Name	Type	Description	Default
session_key	str	The key for the session.	required
data	dict	The data to store in the session.	required

Returns:

Name	Type	Description
str	str	A fake session ID.

delete_session async

delete_session(session_id: str) -> None

Delete a session by its ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to delete.	required

gen_jwt_token async

gen_jwt_token(payload: dict[str, Any]) -> str

Generate a fake JWT token for testing purposes.

This token ALWAYS validates successfully.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	Payload to include in the JWT token.	required

Returns:

Name	Type	Description
str	str	A fake JWT token.

get_otp_code async

get_otp_code(
    secret: str, factor: Optional[int] = None
) -> str

Generates a OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP code.	required
factor	int | None	An optional factor to influence the OTP generation.	None

Returns:

Name	Type	Description
str	str	A fake OTP code.

get_otp_uri async

get_otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP URI.	required
name	str | None	An optional name for the OTP account.	None
issuer	str | None	An optional issuer for the OTP account.	None
counter	int | None	An optional counter for HOTP.	None

Returns:

Name	Type	Description
str	str	A fake otpauth:// URI.

get_session async

get_session(session_id: str) -> Optional[dict[str, Any]]

Retrieve session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to retrieve.	required

Returns:

Type	Description
Optional[dict[str, Any]]	dict | None: The session data if found, otherwise None.

jwt_create_token async

jwt_create_token(payload: dict[str, Any]) -> str

Generate a fake JWT token for testing purposes.

This token ALWAYS validates successfully.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	Payload to include in the JWT token.	required

Returns:

Name	Type	Description
str	str	A fake JWT token.

jwt_make_payload async

jwt_make_payload(
    exp: Optional[int], data: dict[str, Any]
) -> dict[str, Any]

Payload maker tool.

Parameters:

Name	Type	Description	Default
exp	int	Expire	required
data	dict[str, Any]	Arbitrary keyword arguments to include in the payload.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary representing the payload.

jwt_verify_token async

jwt_verify_token(
    token: str,
    check_exp: bool = True,
    check_list: bool = True,
) -> dict[str, Any]

Verify JWT token.

Parameters:

Name	Type	Description	Default
token	str	JWT token to verify.	required
check_exp	bool	Whether to check the expiration time.	True
check_list	bool	Whether to check against a blacklist.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The payload of the verified JWT token.

Raises:

Type	Description
ValueError	If the token format is invalid.

make_payload async

make_payload(**payload: dict[str, Any]) -> dict[str, Any]

Payload maker tool.

Parameters:

Name	Type	Description	Default
**payload	dict[str, Any]	Arbitrary keyword arguments to include in the payload.	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary representing the payload.

oauth2_client_credentials_flow async

oauth2_client_credentials_flow(
    scope: Optional[list[str]] = None, **extra_params: Any
) -> dict[str, Any]

Fake client MtM flow.

oauth2_fetch_token async

oauth2_fetch_token(
    provider: str,
    code: str,
    grant_type: str = "authorization_code",
    **extra_params: Any
) -> dict[str, Any]

Fake fetch token.

oauth2_get_authorized_url async

oauth2_get_authorized_url(
    provider: str, scope: list[str], **extra_params: Any
) -> str

Test oauth2 URL method.

Return FAKE url

oauth2_refresh_token async

oauth2_refresh_token(
    provider: str,
    refresh_token: str,
    grant_type: str = "refresh_token",
    **extra_params: Any
) -> dict[str, Any]

Fake refresh token.

otp_code async

otp_code(
    secret: Union[str, bytes], factor: Optional[int] = None
) -> str

Generates a OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP code.	required
factor	int | None	An optional factor to influence the OTP generation.	None

Returns:

Name	Type	Description
str	str	A fake OTP code.

otp_uri async

otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP URI.	required
name	str | None	An optional name for the OTP account.	None
issuer	str | None	An optional issuer for the OTP account.	None
counter	int | None	An optional counter for HOTP.	None

Returns:

Name	Type	Description
str	str	A fake otpauth:// URI.

otp_verify_code async

otp_verify_code(
    secret: Union[str, bytes],
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = 1,
) -> bool

Verifies a given OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to verify the OTP code.	required
code	str	The OTP code to verify.	required
factor	int | None	An optional factor that was used during OTP generation.	None
look_ahead	int | None	An optional look-ahead window for verification.	1

Returns:

Name	Type	Description
bool	bool	True if the OTP code is valid, False otherwise.

rework_session async

rework_session(old_session_key: str) -> str

Rework an existing session key to a new one.

Parameters:

Name	Type	Description	Default
old_session_key	str	The old session key to be reworked.	required

Returns:

Name	Type	Description
str	str	A new fake session ID.

session_clear async

session_clear(session_key: str) -> None

Clear all sessions associated with a specific session key.

Parameters:

Name	Type	Description	Default
session_key	str	The session key whose sessions are to be cleared.	required

session_create async

session_create(
    session_key: str, data: dict[str, Any]
) -> str

Create new session.

Parameters:

Name	Type	Description	Default
session_key	str	The key for the session.	required
data	dict	The data to store in the session.	required

Returns:

Name	Type	Description
str	str	A fake session ID.

session_delete async

session_delete(session_id: str) -> None

Delete a session by its ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to delete.	required

session_get async

session_get(session_id: str) -> Optional[dict[str, Any]]

Retrieve session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to retrieve.	required

Returns:

Type	Description
Optional[dict[str, Any]]	dict | None: The session data if found, otherwise None.

session_rework async

session_rework(old_session_id: str) -> str

Rework an existing session key to a new one.

Parameters:

Name	Type	Description	Default
old_session_id	str	The old session id to be reworked.	required

Returns:

Name	Type	Description
str	str	A new fake session ID.

session_update async

session_update(
    session_id: str, data: dict[str, Any]
) -> None

Update session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to update.	required
data	dict	The new data for the session.	required

update_session async

update_session(session_id: str, data: dict) -> None

Update session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to update.	required
data	dict	The new data for the session.	required

verify_jwt_token async

verify_jwt_token(
    token: str,
    check_exp: bool = True,
    check_list: bool = True,
) -> dict[str, Any]

Verify JWT token.

Parameters:

Name	Type	Description	Default
token	str	JWT token to verify.	required
check_exp	bool	Whether to check the expiration time.	True
check_list	bool	Whether to check against a blacklist.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The payload of the verified JWT token.

Raises:

Type	Description
ValueError	If the token format is invalid.

verify_otp_code async

verify_otp_code(
    secret: str,
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = None,
) -> bool

Verifies a given OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to verify the OTP code.	required
code	str	The OTP code to verify.	required
factor	int | None	An optional factor that was used during OTP generation.	None
look_ahead	int | None	An optional look-ahead window for verification.	None

Returns:

Name	Type	Description
bool	bool	True if the OTP code is valid, False otherwise.

TestJam

TestJam(
    config: Optional[Union[str, dict[str, Any]]] = None,
    pointer: str = "jam",
)

Bases: Jam

A test client for Jam.

Examples:

import pytest
from jam.tests import TestJam
from jam.tests.fakers import invalid_token

@pytest.fixture
def client() -> TestJam:
    return TestJam()

def test_gen_jwt_token(client) -> None:
    payload = {"user_id": 1, "role": "admin"}
    token = client.gen_jwt_token(payload)
    assert isinstance(token, str)
    assert token.count(".") == 2  # JWT tokens have two dots

def test_verify_jwt_token(client) -> None:
    payload = {"user_id": 1, "role": "admin"}
    token = client.gen_jwt_token(payload)
    verified_payload = client.verify_jwt_token(token, check_exp=False, check_list=False)
    assert verified_payload == payload

def test_invalid_jwt_token(client) -> None:
    token = invalid_token()
    with pytest.raises(ValueError):
        client.verify_jwt_token(token, check_exp=False, check_list=False)

Parameters:

Name	Type	Description	Default
config	str | dict[str, Any] | None	Jam configuration.	None
pointer	str	Pointer for the client instance.	'jam'

Methods:

Name	Description
clear_sessions	Clear all sessions associated with a specific session key.
create_session	Create new session.
delete_session	Delete a session by its ID.
gen_jwt_token	Generate a fake JWT token for testing purposes.
get_otp_code	Generates a OTP code.
get_otp_uri	Generates an otpauth:// URI for Google Authenticator.
get_session	Retrieve session data by session ID.
jwt_create_token	Generate a fake JWT token for testing purposes.
jwt_make_payload	Payload maker tool.
jwt_verify_token	Verify JWT token.
make_payload	Payload maker tool.
oauth2_client_credentials_flow	Fake client MtM flow.
oauth2_fetch_token	Fake fetch token.
oauth2_get_authorized_url	Test oauth2 URL method.
oauth2_refresh_token	Fake refresh token.
otp_code	Generates a OTP code.
otp_uri	Generates an otpauth:// URI for Google Authenticator.
otp_verify_code	Verifies a given OTP code.
rework_session	Rework an existing session key to a new one.
session_clear	Clear all sessions associated with a specific session key.
session_create	Create new session.
session_delete	Delete a session by its ID.
session_get	Retrieve session data by session ID.
session_rework	Rework an existing session key to a new one.
session_update	Update session data by session ID.
update_session	Update session data by session ID.
verify_jwt_token	Verify JWT token.
verify_otp_code	Verifies a given OTP code.

clear_sessions

clear_sessions(session_key: str) -> None

Clear all sessions associated with a specific session key.

Parameters:

Name	Type	Description	Default
session_key	str	The session key whose sessions are to be cleared.	required

create_session

create_session(
    session_key: str, data: dict[str, Any]
) -> str

Create new session.

Parameters:

Name	Type	Description	Default
session_key	str	The key for the session.	required
data	dict	The data to store in the session.	required

Returns:

Name	Type	Description
str	str	A fake session ID.

delete_session

delete_session(session_id: str) -> None

Delete a session by its ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to delete.	required

gen_jwt_token

gen_jwt_token(payload: dict[str, Any]) -> str

Generate a fake JWT token for testing purposes.

This token ALWAYS validates successfully.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	Payload to include in the JWT token.	required

Returns:

Name	Type	Description
str	str	A fake JWT token.

get_otp_code

get_otp_code(
    secret: str, factor: Optional[int] = None
) -> str

Generates a OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP code.	required
factor	int | None	An optional factor to influence the OTP generation.	None

Returns:

Name	Type	Description
str	str	A fake OTP code.

get_otp_uri

get_otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP URI.	required
name	str | None	An optional name for the OTP account.	None
issuer	str | None	An optional issuer for the OTP account.	None
counter	int | None	An optional counter for HOTP.	None

Returns:

Name	Type	Description
str	str	A fake otpauth:// URI.

get_session

get_session(session_id: str) -> Optional[dict[str, Any]]

Retrieve session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to retrieve.	required

Returns:

Type	Description
Optional[dict[str, Any]]	dict | None: The session data if found, otherwise None.

jwt_create_token

jwt_create_token(payload: dict[str, Any]) -> str

Generate a fake JWT token for testing purposes.

This token ALWAYS validates successfully.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	Payload to include in the JWT token.	required

Returns:

Name	Type	Description
str	str	A fake JWT token.

jwt_make_payload

jwt_make_payload(
    exp: Optional[int], data: dict[str, Any]
) -> dict[str, Any]

Payload maker tool.

Parameters:

Name	Type	Description	Default
exp	int | None	Expire	required
data	dict[str, Any]	Arbitrary keyword arguments to include in the payload.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary representing the payload.

jwt_verify_token

jwt_verify_token(
    token: str,
    check_exp: bool = True,
    check_list: bool = True,
) -> dict[str, Any]

Verify JWT token.

Parameters:

Name	Type	Description	Default
token	str	JWT token to verify.	required
check_exp	bool	Whether to check the expiration time.	True
check_list	bool	Whether to check against a blacklist.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The payload of the verified JWT token.

Raises:

Type	Description
ValueError	If the token format is invalid.

make_payload

make_payload(**payload: dict[str, Any]) -> dict[str, Any]

Payload maker tool.

Parameters:

Name	Type	Description	Default
**payload	dict[str, Any]	Arbitrary keyword arguments to include in the payload.	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary representing the payload.

oauth2_client_credentials_flow

oauth2_client_credentials_flow(
    scope: Optional[list[str]] = None, **extra_params: Any
) -> dict[str, Any]

Fake client MtM flow.

oauth2_fetch_token

oauth2_fetch_token(
    provider: str,
    code: str,
    grant_type: str = "authorization_code",
    **extra_params: Any
) -> dict[str, Any]

Fake fetch token.

oauth2_get_authorized_url

oauth2_get_authorized_url(
    provider: str, scope: list[str], **extra_params: Any
) -> str

Test oauth2 URL method.

Return FAKE url

oauth2_refresh_token

oauth2_refresh_token(
    provider: str,
    refresh_token: str,
    grant_type: str = "refresh_token",
    **extra_params: Any
) -> dict[str, Any]

Fake refresh token.

otp_code

otp_code(
    secret: Union[str, bytes], factor: Optional[int] = None
) -> str

Generates a OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP code.	required
factor	int | None	An optional factor to influence the OTP generation.	None

Returns:

Name	Type	Description
str	str	A fake OTP code.

otp_uri

otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to generate the OTP URI.	required
name	str | None	An optional name for the OTP account.	None
issuer	str | None	An optional issuer for the OTP account.	None
counter	int | None	An optional counter for HOTP.	None

Returns:

Name	Type	Description
str	str	A fake otpauth:// URI.

otp_verify_code

otp_verify_code(
    secret: Union[str, bytes],
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = 1,
) -> bool

Verifies a given OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to verify the OTP code.	required
code	str	The OTP code to verify.	required
factor	int | None	An optional factor that was used during OTP generation.	None
look_ahead	int | None	An optional look-ahead window for verification.	1

Returns:

Name	Type	Description
bool	bool	True if the OTP code is valid, False otherwise.

rework_session

rework_session(old_session_key: str) -> str

Rework an existing session key to a new one.

Parameters:

Name	Type	Description	Default
old_session_key	str	The old session key to be reworked.	required

Returns:

Name	Type	Description
str	str	A new fake session ID.

session_clear

session_clear(session_key: str) -> None

Clear all sessions associated with a specific session key.

Parameters:

Name	Type	Description	Default
session_key	str	The session key whose sessions are to be cleared.	required

session_create

session_create(
    session_key: str, data: dict[str, Any]
) -> str

Create new session.

Parameters:

Name	Type	Description	Default
session_key	str	The key for the session.	required
data	dict	The data to store in the session.	required

Returns:

Name	Type	Description
str	str	A fake session ID.

session_delete

session_delete(session_id: str) -> None

Delete a session by its ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to delete.	required

session_get

session_get(session_id: str) -> Optional[dict[str, Any]]

Retrieve session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to retrieve.	required

Returns:

Type	Description
Optional[dict[str, Any]]	dict | None: The session data if found, otherwise None.

session_rework

session_rework(old_session_id: str) -> str

Rework an existing session key to a new one.

Parameters:

Name	Type	Description	Default
old_session_id	str	The old session id to be reworked.	required

Returns:

Name	Type	Description
str	str	A new fake session ID.

session_update

session_update(
    session_id: str, data: dict[str, Any]
) -> None

Update session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to update.	required
data	dict	The new data for the session.	required

update_session

update_session(session_id: str, data: dict) -> None

Update session data by session ID.

Parameters:

Name	Type	Description	Default
session_id	str	The ID of the session to update.	required
data	dict	The new data for the session.	required

verify_jwt_token

verify_jwt_token(
    token: str,
    check_exp: bool = True,
    check_list: bool = True,
) -> dict[str, Any]

Verify JWT token.

Parameters:

Name	Type	Description	Default
token	str	JWT token to verify.	required
check_exp	bool	Whether to check the expiration time.	True
check_list	bool	Whether to check against a blacklist.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The payload of the verified JWT token.

Raises:

Type	Description
ValueError	If the token format is invalid.

verify_otp_code

verify_otp_code(
    secret: str,
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = None,
) -> bool

Verifies a given OTP code.

Parameters:

Name	Type	Description	Default
secret	str	The secret key used to verify the OTP code.	required
code	str	The OTP code to verify.	required
factor	int | None	An optional factor that was used during OTP generation.	None
look_ahead	int | None	An optional look-ahead window for verification.	None

Returns:

Name	Type	Description
bool	bool	True if the OTP code is valid, False otherwise.

FILE PATH: jam/tests/clients.py