SDK reference#
The Python SDK — use it to build TestZeus into your own apps, services, and automation. Install with pip install testzeus-sdk, then from testzeus_sdk import TestZeusClient.
Source: test-zeus-ai/testzeus-sdk · auto-generated from this repo on every build (nightly + on source change) — to change this page, change the code
Quick example#
Create an async client (email/password, or env vars), then call the managers:
import asyncio
from testzeus_sdk import TestZeusClient
async def main():
async with TestZeusClient(email="[email protected]", password="...") as client:
tests = await client.tests.get_list(sort="id") # list tests
test = await client.tests.get_one(tests["items"][0].id) # fetch one
print(test.name, test.status)
asyncio.run(main())
Tip
In CI, set TESTZEUS_EMAIL / TESTZEUS_PASSWORD as env vars and call TestZeusClient() with no arguments.
Every manager (tests, test runs, environments, tags, and more) supports filtering and sorting — e.g. get_list(filters={"status": "active"}, sort="-created"). The full class and method reference follows.
TestZeusClient#
Client for interacting with TestZeus API.
This client wraps the PocketBase client and provides access to all TestZeus functionality through specialized managers for each entity type.
ensure_authenticated()#
Ensure the client is authenticated before making API calls
authenticate(email: str, password: str)#
Authenticate with email and password
Args: email: User email password: User password
Returns: Authentication token
request(method: str, endpoint: str, params: Optional[Dict[str, Any]] = None, json_data: Optional[Dict[str, Any]] = None, data: Optional[Any] = None)#
Make an API request
Args: method: HTTP method (GET, POST, PATCH, DELETE) endpoint: API endpoint (starting with /) params: Query parameters json_data: JSON body for POST/PATCH requests data: Form data for POST requests
Returns: API response as dictionary
is_authenticated()#
Check if the client is authenticated
Returns: True if authenticated
logout()#
Logout and clear authentication state
get_tenant_id()#
Get the current tenant ID
Returns: Tenant ID or default tenant ID if not authenticated
get_tenant_id_async()#
Get the current tenant ID (async version)
get_user_id()#
Get the current User ID
Returns: User ID or empty string if not authenticated or not implemented
get_user_id_async()#
Get the current User ID (async version)
get_file_token()#
Get the current file token
set_tenant_id(tenant_id: str)#
Explicitly set the tenant ID to use for operations
Args: tenant_id: The tenant ID to use
AdversaryPathwaysGenerationManager#
BaseManager-backed manager for adversary pathway generation jobs.
create(data: Dict[str, Any])#
Create a generation job.
This collection requires created_by in addition to the tenant + modified_by that BaseManager injects, so fill it from the session too.
AdversaryPathwaysGroupManager#
BaseManager-backed manager for adversary simulation run groups.
create(data: Dict[str, Any])#
Create a run group.
This collection requires created_by in addition to the tenant + modified_by that BaseManager injects, so fill it from the session too.
AdversaryPathwaysManager#
BaseManager-backed manager for adversary pathway (test scenario) records.
create(data: Dict[str, Any])#
Create a pathway (tenant + modified_by auto-injected by BaseManager).
AdversarySimulationsManager#
BaseManager-backed manager for adversary simulation records.
Simulations are created by the backend workflow when a run group is
submitted, so this manager is read-oriented (get_list / get_one);
the SDK never creates simulation records directly.
AgentConfigsManager#
Manager for AgentConfigs resources
AgentHarnessManager#
Facade for the Agent Harness (adversarial agent testing) subsystem.
list_agents(page: int = 1, per_page: int = 50, status: Optional[str] = None, search: Optional[str] = None, type: Optional[str] = None)#
List available agents (custom gateway-pb endpoint).
get_agent(agent_id: str)#
Get a single agent’s detail (custom gateway-pb endpoint).
list_pathways(agent_id: Optional[str] = None, page: int = 1, per_page: int = 50)#
List adversarial test pathways, optionally scoped to one agent.
Delegates to the sub-manager’s get_list so the filter is built by the
shared _build_filter_string (value-escaped) and items come back as
AdversaryPathways model instances.
create_pathway(data: Dict[str, Any])#
Create a custom adversarial pathway (tenant + modified_by auto-filled).
delete_pathway(pathway_id: str)#
Soft-delete a pathway (PATCH is_deleted=True through BaseManager.update).
generate_pathways(agent_profile: str, directional_prompt: str, name: Optional[str] = None, agent_name: Optional[str] = None, num_pathways: Optional[int] = None, allow_destructive: bool = False, status: str = 'pending')#
Start an AI pathway-generation job for a Salesforce agent profile.
Creates an adversary_pathways_generation record via the sub-manager
(is_submit=True triggers the workflow). tenant/created_by/modified_by
are auto-filled from the authenticated session by the manager.
run(agent_id: str, pathway_ids: List[str], name: Optional[str] = None, agent_name: Optional[str] = None, run_as_profile: Optional[str] = None, status: str = 'pending')#
Start a simulation run (create an adversary_pathways_group record).
tenant/created_by/modified_by are auto-filled from the session by the
sub-manager; returns a typed AdversaryPathwaysGroup model.
list_simulations(group_id: Optional[str] = None, page: int = 1, per_page: int = 50)#
List adversarial simulations, optionally scoped to one run group.
Delegates to the sub-manager’s get_list so the filter is built by the
shared _build_filter_string (value-escaped) and items come back as
AdversarySimulations model instances.
get_simulation(simulation_id: str)#
Get a single adversarial simulation by id.
get_status(group_id: str)#
Get full simulation-group status (custom gateway-pb endpoint).
cancel(group_id: str)#
Cancel a running simulation group (custom gateway-pb endpoint).
run_and_wait(agent_id: str, pathway_ids: List[str], name: Optional[str] = None, agent_name: Optional[str] = None, run_as_profile: Optional[str] = None, poll_interval: float = 3.0, timeout: float = 1800.0)#
Start a run and poll its status until the group reaches a terminal state.
get_sf_profiles(connection_id: str)#
Get Salesforce user profiles for the Run-As-User (RBAC) picker.
SessionExchangeResponse#
Response from session exchange via auth-refresh.
from_dict(cls, data: Dict[str, Any])#
Create from API response dict.
SessionValidateResponse#
Response from validating a session token.
AuthManager#
Manager for authentication operations.
Provides session exchange functionality using existing PocketBase auth-refresh. This allows Hermes to exchange a UI-provided PocketBase JWT for CLI-compatible auth.
exchange_session(pb_token: str)#
Exchange a PocketBase JWT for a refreshed session token.
This calls POST /api/collections/users/auth-refresh with the provided PocketBase JWT. The refreshed token can be used for CLI operations.
Args: pb_token: PocketBase JWT token from UI
Returns: SessionExchangeResponse with token and user info
Raises: ValueError: If token exchange fails
validate_token(token: str)#
Validate a token by attempting to refresh it.
Args: token: Token to validate
Returns: SessionValidateResponse with validation result
extract_token_info(token: str)#
Extract basic info from a JWT without validation.
This decodes the payload (middle part) of a JWT without verifying the signature. Useful for quick token inspection.
Args: token: JWT token
Returns: Dict with token info (userId, tenantId, exp, etc.) or None if invalid
is_token_expired(token: str)#
Check if a token is expired based on its ‘exp’ claim.
Args: token: JWT token
Returns: True if token is expired, False otherwise
BaseManager#
Base manager class for all TestZeus entities.
This class provides common CRUD operations for all entity types.
get_list(page: int = 1, per_page: int = 30, filters: Optional[Dict[str, Any]] = None, sort: Optional[Union[str, List[str]]] = None, expand: Optional[Union[str, List[str]]] = None)#
Get a list of entities with optional filtering.
Args: page: Page number (1-based) per_page: Number of items per page filters: Dictionary of filter conditions sort: Field(s) to sort by (prefix with ‘-’ for descending order) expand: Related collection(s) to expand
Returns: Dictionary containing items and pagination info
get_one(id_or_name: str, expand: Optional[Union[str, List[str]]] = None)#
Get a single entity by ID or name.
Args: id_or_name: Entity ID or name expand: Fields to expand in the response
Returns: Entity model instance
get_first_item(filters: Optional[Dict[str, Any]] = None)#
Get the first item from the collection based on optional filters.
Args: filters: Dictionary of filter conditions
Returns: First item from the collection
check_duplicate(data: Dict[str, Any])#
Check if a record with the same name exists in the current tenant.
Args: data: Entity data to check for duplicates
Returns: Existing record if found, None otherwise
create(data: Dict[str, Any])#
Create a new entity.
Args: data: Entity data
Returns: Created entity model instance
Raises: ValueError: If a record with the same name already exists or if creation fails
update(id_or_name: str, data: Dict[str, Any])#
Update an existing entity.
Args: id_or_name: Entity ID or name data: Updated entity data
Returns: Updated entity model instance
delete(id_or_name: str)#
Delete an entity.
Args: id_or_name: Entity ID or name
Returns: True if deletion was successful
ConnectedEnvironmentManager#
Manager class for TestZeus connected environment entities.
This class provides CRUD operations and specialized methods for working with connected environment entities.
create(data: Dict[str, Any])#
Create a new connected environment.
Args: data: Connected environment data
Returns: Created connected environment instance
update(id_or_name: Text, data: Dict[str, Any])#
Update an existing connected environment.
Args: id_or_name: Connected environment ID or name data: Updated connected environment data
Returns: Updated connected environment instance
add_metadata_file(id_or_name: str, file_path: str)#
Add a metadata file to a connected environment.
Args: id_or_name: Connected environment ID or name file_path: Path to the file to add
Returns: Updated connected environment instance
remove_metadata_file(id_or_name: str, file_name: str)#
Remove a metadata file from a connected environment.
Args: id_or_name: Connected environment ID or name file_name: Name of the file to remove
Returns: Updated connected environment instance
remove_all_metadata_files(id_or_name: str)#
Remove all metadata files from a connected environment.
Args: id_or_name: Connected environment ID or name
Returns: Updated connected environment instance
add_code_file(id_or_name: str, file_path: str)#
Add a code file to a connected environment.
Args: id_or_name: Connected environment ID or name file_path: Path to the file to add
Returns: Updated connected environment instance
remove_code_file(id_or_name: str, file_name: str)#
Remove a code file from a connected environment.
Args: id_or_name: Connected environment ID or name file_name: Name of the file to remove
Returns: Updated connected environment instance
remove_all_code_files(id_or_name: str)#
Remove all code files from a connected environment.
Args: id_or_name: Connected environment ID or name
Returns: Updated connected environment instance
DevicePoolManager#
Read-only manager for TestZeus device pool entities.
Device pool entries represent available mobile devices for test execution. Create, update, and delete operations are not supported.
create(data: Dict[str, Any])#
update(id_or_name: str, data: Dict[str, Any])#
delete(id_or_name: str)#
EnvironmentManager#
Manager class for TestZeus environment entities.
This class provides CRUD operations and specialized methods for working with environment entities.
create(data: Dict[str, Any])#
Create a new environment.
Args: data: Environment data
Returns: Created environment instance
update(id_or_name: Text, data: Dict[str, Any])#
Update an existing environment.
Args: id_or_name: Environment ID or name data: Updated environment data
Returns: Updated environment instance
add_file(id_or_name: str, file_name: str)#
Add a supporting data file to a browser environment.
remove_file(id_or_name: str, file_name: str)#
Remove a supporting data file from a browser environment.
file_name may be the stored file name, the original upload name (display name), or a local path to the originally uploaded file.
Raises: ValueError: If no stored file matches the given file name
remove_all_files(id_or_name: str)#
Remove all supporting data files from a browser environment.
add_mobile_file(id_or_name: str, file_name: str)#
Upload a mobile app file (APK/ZIP) to a mobile environment.
remove_mobile_file(id_or_name: str)#
Remove the mobile app file from a mobile environment.
add_tags(id_or_name: str, tags: List[str])#
Add tags to an environment.
Args: id_or_name: Environment ID or name tags: List of tag names or IDs
Returns: Updated environment instance
ExtensionManager#
Manager class for TestZeus extension entities.
This class provides CRUD operations for working with extension entities.
HypermindCodeBlocksManager#
Manager class for TestZeus hypermind_code_blocks entities.
This class provides CRUD operations and specialized methods for working with hypermind_code_blocks entities.
create(data: Dict[str, Any])#
Create a new hypermind code blocks.
Args: data: HypermindCodeBlocks data
Returns: Created hypermind_code_blocks instance
update(id_or_name: Text, data: Dict[str, Any])#
Update existing hypermind code blocks.
Args: id_or_name: HypermindCodeBlocks ID or name data: Updated hypermind_code_blocks data
Returns: Updated hypermind_code_blocks instance
add_file(id_or_name: str, file_name: str)#
Add a file to hypermind code blocks.
remove_file(id_or_name: str, file_name: str)#
Remove a file from hypermind code blocks.
remove_all_files(id_or_name: str)#
Remove all files from hypermind code blocks.
add_tags(id_or_name: str, tags: List[str])#
Add tags to hypermind code blocks.
Args: id_or_name: HypermindCodeBlocks ID or name tags: List of tag names or IDs
Returns: Updated hypermind_code_blocks instance
KnowledgeBaseManager#
Manager for KnowledgeBase resources.
Provides CRUD operations for managing knowledge bases which are used to enhance test generation with contextual information.
NotificationChannelManager#
Manager class for TestZeus notification channel entities.
This class provides CRUD operations for working with notification channel entities.
create_notification_channel(name: str, emails: list[str], display_name: str = None, tenant: str = None, created_by: str = None, webhooks: list[str] = None, slack: SlackConfig = None, jira: dict[str, any] = None, is_active: bool = True, is_default: bool = True)#
Create a new notification channel. Args: name: Name of the notification channel display_name: Display name of the notification channel tenant: Tenant ID (optional, will use authenticated tenant if not provided) created_by: user ID (optional, will use authenticated user if not provided) emails: list of emails webhooks: list of webhooks slack: dictionary of slack config with token and channel_id example: {“token”: “xoxb-your-token”, “channel_id”: “C0605HWSGNN”} jira: dictionary of jira config with project_key and issue_type example: {“project_key”: “TEST”, “issue_type”: “Task”} is_active: Set as active notification channel (default: True) is_default: Set as default notification channel (default: True) Returns: NotificationChannel: The created notification channel
update_notification_channel(id_or_name: str, name: str = None, display_name: str = None, tenant: str = None, created_by: str = None, emails: list[str] = None, webhooks: list[str] = None, slack: SlackConfig = None, jira: dict[str, any] = None, is_active: bool = True, is_default: bool = True)#
Update a notification channel. Args: id_or_name: ID or name of the notification channel name: Name of the notification channel display_name: Display name of the notification channel tenant: Tenant ID (optional, will use authenticated tenant if not provided) created_by: user ID (optional, will use authenticated user if not provided) emails: list of emails webhooks: list of webhooks slack: dictionary of slack config with token and channel_id example: {“token”: “xoxb-your-token”, “channel_id”: “C0605HWSGNN”} jira: dictionary of jira config with project_key and issue_type example: {“project_key”: “TEST”, “issue_type”: “Task”} is_active: Set as active notification channel (default: True) is_default: Set as default notification channel (default: True) Returns: NotificationChannel: The updated notification channel
remove_config(id_or_name: str, config_type: Literal['webhook', 'slack', 'jira'])#
Remove a configuration from a notification channel. Args: id_or_name: ID or name of the notification channel config_type: Type of configuration to remove Returns: NotificationChannel: The updated notification channel
TagManager#
Manager class for TestZeus tag entities.
This class provides CRUD operations and specialized methods for working with tag entities.
create(data: Dict[str, Any])#
Create a new tag.
Args: data: Tag data
Returns: Created tag instance
create_tag(name: str, value: Optional[str] = None)#
Create a new tag with individual fields.
Args: name: Name of the Tag value: Value for the Tag
Returns: Created tag instance
update(id_or_name: str, data: Dict[str, Any])#
Update an existing tag.
Args: id_or_name: Tag ID or name data: Updated tag data
Returns: Updated tag instance
update_tag(id_or_name: str, name: Optional[str] = None, value: Optional[str] = None)#
Update an existing tag with individual fields.
Args: id_or_name: Tag ID or name name: New name for the Tag value: New value for the Tag (pass “” to clear it)
Returns: Updated tag instance
Raises: ValueError: If neither name nor value is provided
find_or_create(name: str, value: Optional[str] = None)#
Find a tag by name or create it if it doesn’t exist.
Args: name: Tag name value: Optional tag value
Returns: Existing or newly created tag instance
TenantConsumptionLogsManager#
Manager for TenantConsumptionLogs resources
TenantConsumptionManager#
Manager for TenantConsumption resources
TenantsManager#
Manager for Tenants resources
TestDataManager#
Manager class for TestZeus test data entities.
This class provides CRUD operations and specialized methods for working with test data entities.
create(data: Dict[str, Any])#
Create a new test data entity.
Args: data: Test data with potentially name-based references
Returns: Created test data instance
add_file(id_or_name: str, file_name: str)#
Add a file to a test data entity.
remove_file(id_or_name: str, file_name: str)#
Remove a file from a test data entity.
file_name may be the stored file name, the original upload name (display name), or a local path to the originally uploaded file.
Raises: ValueError: If no stored file matches the given file name
remove_all_files(id_or_name: str)#
Remove all files from a test data entity.
download_all_files(id_or_name: str, output_dir: str = 'downloads')#
Download all supporting files from a test data collection.
Args: id_or_name (str): The ID or name of the test data collection output_dir (str, optional): Directory to save the downloaded files. Defaults to “downloads”.
Returns: List[str]: List of paths to the downloaded files
TestDesignsManager#
Manager for TestDesigns resources
TestDeviceManager#
Manager for TestDevice resources
TestManager#
Manager class for TestZeus test entities.
This class provides CRUD operations and specialized methods for working with test entities.
create(data: Dict[str, Any])#
Create a new Test entity.
Args: data: Test data
Returns: Test: The created Test instance.
update(id_or_name: str, data: Dict[str, Any])#
Update an existing Test entity.
Args: id_or_name: Test ID or name data: Updated test data
Returns: Test: The updated Test instance.
get_input_params(test_id: str)#
Fetch merged input parameters and defaults for a test.
get_dependent_test_suites(test_id: str)#
Fetch test suites whose extracted tests relation includes this test.
add_tags(id_or_name: str, tags: List[str])#
Add tags to a test.
Args: id_or_name: Test ID or name tags: List of tag names or IDs
Returns: Updated test instance
TestReportDashRunManager#
Manager class for TestZeus test report dash run entities.
This class provides CRUD operations for working with test report dash run entities.
TestReportRunManager#
Manager class for TestZeus test report run entities.
This class provides CRUD operations for working with test report run entities.
download_report(id_or_name: str, output_dir: str = 'downloads', format: str = Literal['ctrf', 'pdf', 'csv', 'zip'])#
Download the report for a test report run.
TestReportScheduleManager#
Manager class for TestZeus test report schedule entities.
This class provides CRUD operations for working with test report schedule entities.
TestRunDashOutputStepsManager#
Manager for TestRunDashOutputSteps resources
TestRunDashOutputsAttachmentsManager#
Manager for TestRunDashOutputsAttachments resources
download_attachment(id_or_name: str, output_dir: str = '.')#
Download an attachment file by its ID or name.
Args: id_or_name: ID or name of the attachment output_dir: Directory where the file should be downloaded to (defaults to current directory)
Returns: Path to the downloaded file as string if successful, None otherwise
TestRunDashOutputsManager#
Manager for TestRunDashOutputs resources
TestRunDashsManager#
Manager for TestRunDashs resources
get_expanded(test_run_id: str)#
Get complete expanded tree of a test run with all details
Args: test_run_id: Test run ID
Returns: Complete test run tree with all details
cancel(test_run_id: str)#
Cancel a test run
Args: test_run_id: Test run ID
Returns: True if successful
TestRunGroupManager#
Manager class for TestZeus test run group entities.
This class provides CRUD operations and specialized methods for working with test run group entities.
cancel_group(id_or_name: str)#
Cancel all running test runs in a group.
Args: id_or_name: Test run group ID or name
Returns: Updated test run group instance
download_report(id_or_name: str, output_dir: str = 'downloads', format: Literal['ctrf', 'pdf', 'csv', 'zip'] = 'pdf')#
Download the report for a test run group.
download_all_attachments(id_or_name: str, output_dir: str = 'downloads')#
Download all attachments for all test runs in a test run group. Each test run will have its own folder within the test run group folder.
Args: id_or_name: Test run group ID or name output_dir: Base directory to save attachments (default: “downloads”)
Returns: Dictionary mapping test run names to lists of downloaded attachment filenames
Directory structure: downloads/
TestRunManager#
Manager class for TestZeus test run entities.
This class provides CRUD operations and specialized methods for working with test run entities.
cancel(id_or_name: str, modified_by: Optional[str] = None, tenant: Optional[str] = None)#
Cancel a test run.
Args: id_or_name: Test run ID or name modified_by: User ID who is canceling the test run (optional) tenant: Tenant ID to associate with this operation (optional)
Returns: Updated test run instance
cancel_with_email(id_or_name: str, user_email: str)#
Cancel a test run using user email instead of user ID.
Args: id_or_name: Test run ID or name user_email: Email of the user canceling the test run
Returns: Updated test run instance
Raises: ValueError: If user with the email is not found
get_expanded(id_or_name: str)#
Get a test run with all expanded details including outputs, steps, and attachments.
Args: id_or_name: Test run ID or name
Returns: Complete test run tree with all details
download_all_attachments(id_or_name: str, output_dir: str = '.')#
Download all attachments for a test run.
Args: id_or_name: Test run ID or name output_dir: Directory to save attachments
Returns: List of downloaded attachment filenames
run_multiple_tests_and_generate_ctrf_report(test_ids: list[str], tenant: str = None, modified_by: str = None, execution_mode: Literal['lenient', 'strict'] = 'lenient', ctrf_filename: str = 'ctrf_report.json', interval: int = 30)#
Run multiple tests, monitor their progress, and generate CTRF report once completed.
Args: test_ids: List of test IDs tenant: Tenant ID to associate with this test run (optional) modified_by: User ID who is modifying the test run (optional) execution_mode: Execution mode for the test run (optional) ctrf_filename: Custom filename for CTRF report (optional)
Returns: Tuple containing: - List of completed test runs - Path to the generated CTRF report
TestRunReportsManager#
Manager for TestRunReports resources
TestRunsManager#
Manager for TestRuns resources
TestRunsStageManager#
Manager for TestRunsStage resources
TestSuiteManager#
Manager class for TestZeus test suite entities.
TestSuiteNodeRunManager#
Manager class for TestZeus test suite node run entities.
TestSuiteRunManager#
Manager class for TestZeus test suite run entities.
pause(suite_run_id: str, mode: str = 'graceful', reason: Optional[str] = None)#
resume(suite_run_id: str)#
cancel(suite_run_id: str)#
run(display_name: str, test_suite: str, input_values: Optional[Dict[str, Any]] = None, environment: Optional[str] = None, notification_channels: Optional[List[str]] = None)#
Create and start a test suite run.
Args: display_name: Display name for the test suite run test_suite: Test suite ID or name input_values: Input values for the workflow (optional) environment: Environment ID or name (optional) notification_channels: List of notification channel IDs or names (optional)
Returns: Created test suite run instance
TestSuiteScheduleManager#
Manager class for TestZeus test suite schedule entities.
TestsAIGeneratorManager#
Manager class for TestZeus tests AI generator entities.
This class provides CRUD operations for working with tests AI generator entities.
create(data: Dict[str, Any])#
TestsManager#
Manager for Tests resources
UserIntegrationManager#
Manager class for TestZeus user_integration entities.
This class provides read-only operations for user_integration entities.
get_one(id_or_name: str, expand: Optional[Union[str, List[str]]] = None)#
Get a single user integration by ID or name.
Args: id_or_name: UserIntegration ID or name expand: Fields to expand in the response
Returns: UserIntegration model instance
UsersManager#
Manager for Users resources
find_by_email(email: str)#
Find a user by email address.
Args: email: User email address
Returns: User instance if found, None otherwise