Refresh or reconnect the ALM session.

Use this if other tools start returning authentication or session errors. Tries a heartbeat first; reconnects fully if that fails.

Returns: {"refreshed": true, "reconnected": true/false}

Ensure a Test Plan folder path exists, creating any missing folders.

Args: folder_path: '/' separated path, e.g. 'AppName/Sprint1/Regression'.

Returns: {"folder_id": "", "folder_path": ""}

Ensure a Test Lab (test-set) folder path exists, creating any missing folders.

Args: folder_path: '/' separated path, e.g. 'Automation/Sprint1'.

Returns: {"folder_id": "", "folder_path": ""}

List all test cases inside a Test Plan folder.

Args: folder_id: ALM numeric ID of the test plan folder.

Returns: {"tests": [{"id", "name", "status", "owner"}, ...], "count": , "folder_id": ""}

Get the full details of a test case by ID, including all ALM fields.

Args: test_id: ALM numeric ID of the test case.

Returns: {"test_id": "", "fields": {all ALM field names and values}}

Look up a test case ID by its exact name.

Args: test_name: Exact name of the test case in ALM.

Returns: {"found": true/false, "test_id": "", "test_name": ""}

Create a manual test case in a Test Plan folder, optionally with design steps.

Handles check-out/check-in automatically when steps are provided.

Args: folder_id: ID of the parent folder. test_name: Name for the new test case. steps: Optional list of design steps. Each step is a dict with keys: "name" (step number/title), "description", "expected".

Returns: {"test_id": "", "test_name": "", "folder_id": "", "steps_added": }

Update any field(s) on an existing test case.

Common fields: "name", "status", "description", "owner", "priority", "subtype-id". The test case must be checked out — set auto_checkout=true to handle this automatically.

Args: test_id: ALM ID of the test case. fields: Dict of ALM field names → new values. Example: {"status": "Ready", "owner": "jsmith", "description": "Updated desc"}. auto_checkout: If true (default), checks out before and checks in after editing.

Returns: {"test_id", "fields_updated": [...], "vc_status": ""}

Create multiple test cases with design steps under a folder path in one call.

Creates any missing folders along the path automatically.

Args: folder_path: '/' separated path e.g. 'AppName/Sprint1/Smoke'. test_cases: List of test case dicts: [{"name": "TC-001", "steps": [{"name": "Step 1", "description": "Navigate to login", "expected": "Login page is shown"}]}]

Returns: {"folder_id": "", "created": [...], "failed": [...]}

Get the version control status of a test case (Checked_In or Checked_Out).

Args: test_id: ALM ID of the test case.

Returns: {"test_id": "", "vc_status": "Checked_In" | "Checked_Out" | null}

Check out a test case so its fields and design steps can be edited.

Args: test_id: ALM ID of the test case.

Returns: {"test_id": "", "vc_status": ""}

Check in a test case after editing to save a new version in ALM.

Args: test_id: ALM ID of the test case.

Returns: {"test_id": "", "vc_status": ""}

Add design steps to a test case (test must already be checked out).

Args: test_id: ALM ID of the test case (must be in Checked_Out state). steps: List of steps, each a dict with "name", "description", "expected". Example: [{"name": "Step 1", "description": "Open browser", "expected": "Browser opens"}] delete_existing: If true, deletes all current steps before adding new ones.

Returns: {"test_id": "", "steps_added": , "delete_existing": true/false}

Find a test set in Test Lab by its exact name and return its ID.

Args: test_set_name: Exact name of the test set.

Returns: {"found": true/false, "test_set_id": "", "test_set_name": ""}

Create a new test set inside a Test Lab folder.

Args: parent_folder_id: ID of the test-set folder (use alm_ensure_test_lab_folder). test_set_name: Name for the new test set.

Returns: {"test_set_id": "", "test_set_name": "", "parent_folder_id": ""}

Pull (add) a test case from Test Plan into a Test Lab test set.

This is the 'Move TC from Test Plan to Test Lab' operation in ALM.

Args: test_set_id: ID of the target test set. test_id: ID of the test case in Test Plan. status: Initial run status — 'No Run', 'Passed', 'Failed', 'Blocked'.

Returns: {"success": true/false, "test_instance_id": "", "test_set_id", "test_id"}

List all test instances (pulled tests) inside a test set.

Args: test_set_id: ID of the test set.

Returns: {"instances": [{"id", "name", "status"}, ...], "count": , "test_set_id": ""}

Find a test instance inside a test set by test case name (partial match supported).

Args: test_set_id: ID of the test set. test_case_name: Name of the test case (exact or partial match).

Returns: {"found": true/false, "test_instance_id": "", "test_case_name", "test_set_id"}

Get the test configuration ID for a test case (required internally to create test runs).

Args: test_id: ALM ID of the test case.

Returns: {"found": true/false, "test_config_id": "", "test_id": ""}

Create a manual test run record for an existing test instance.

Args: test_id: ALM ID of the test case. test_set_id: ALM ID of the test set (cycle). test_instance_id: ALM ID of the test instance inside the test set. test_name: Display name/label for this run. status: Initial status — 'Not Completed', 'Passed', 'Failed', 'Blocked'. peer_reviewer: Optional ALM username to set as peer reviewer (user-template-06 field).

Returns: {"success": true/false, "test_run_id": "", "test_name", "status"}

Update the overall pass/fail status of a test run.

Args: test_run_id: ALM ID of the run. status: 'Passed', 'Failed', 'Not Completed', 'Blocked'.

Returns: {"test_run_id": "", "status": "", "updated": true}

Get all run steps for a test run, sorted by step order.

Returns step IDs and order numbers — use these to map evidence (screenshots) to the correct step before calling alm_update_run_step or alm_attach_to_entity.

Args: test_run_id: ALM ID of the run.

Returns: {"test_run_id": "", "run_steps": [{"id", "step_order", "name"}, ...], "count": }

Update the status and actual-result comment for a single run step.

Args: test_run_id: ALM ID of the run. run_step_id: ALM ID of the run step (from alm_get_run_steps). status: 'Passed', 'Failed', 'Not Completed'. comments: Actual result / comments text to record against this step.

Returns: {"test_run_id", "run_step_id", "status", "updated": true}

Full end-to-end test execution in a single call.

Finds the test instance → creates a run → updates run status → updates all run steps. This is the primary tool for recording automation results in ALM.

Args: test_set_id: ALM ID of the test set containing the test instance. test_id: ALM ID of the test case in Test Plan. test_name: Name matching the test instance in the test set. status: 'Passed' or 'Failed'. comments: Optional comment written to step actual-result field. peer_reviewer: Optional ALM username to set as peer reviewer (user-template-06).

Returns: {"success": true/false, "test_run_id", "status", "steps_updated": }

List defects from the project with optional HPQL filter.

Args: query: HPQL filter string (without braces). Examples: "status[Open]" "status[Open];priority[4-Very High]" "owner[jsmith]" "name[login]" Leave empty to list all defects up to page_size. page_size: Maximum number of defects to return (default 100).

Returns: {"defects": [...], "count": }

Get the full details of a defect by its ID.

Args: defect_id: ALM numeric ID of the defect.

Returns: {"defect_id": "", "fields": {all ALM field names and values}}

Create a new defect (bug) in the ALM project.

Args: name: Defect summary / title (required). severity: '1-Low', '2-Medium', '3-High', '4-Very High'. priority: '1-Low', '2-Medium', '3-High', '4-Very High'. description: Detailed description of the defect. extra_fields: Any additional ALM field names → values, e.g. {"owner": "jsmith", "status": "Open", "detected-in-rel": "2.1", "environment": "QA", "component": "Login"}.

Returns: {"success": true, "defect_id": "", "name": ""}

Update any field(s) on an existing defect.

Common fields: "status", "priority", "severity", "owner", "description", "closing-version", "fix-version", "environment", "component".

Args: defect_id: ALM ID of the defect to update. fields: Dict of ALM field names → new values. Example: {"status": "Fixed", "owner": "jsmith", "closing-version": "2.1"}

Returns: {"defect_id": "", "fields_updated": [...], "updated": true}

List requirements from the project with optional HPQL filter.

Args: query: HPQL filter string, e.g. "status[Not Covered]", "priority[4-Very High]". Leave empty to list all requirements up to page_size. page_size: Maximum number of results (default 100).

Returns: {"requirements": [...], "count": }

Get the full details of a requirement by ID.

Args: req_id: ALM numeric ID of the requirement.

Returns: {"req_id": "", "fields": {all ALM field names and values}}

Create a new requirement in the ALM project.

Args: name: Requirement name / title (required). req_type: Requirement type, e.g. 'Business', 'Functional', 'Testing', 'Undefined'. description: Detailed requirement description. extra_fields: Optional dict of additional ALM field names → values.

Returns: {"success": true, "req_id": "", "name": ""}

Upload a local file as an attachment to any ALM entity.

Supports screenshots, test reports, logs, and any other file type.

Args: entity_type: ALM collection name — one of: 'runs' → attach to a test run (reports, screenshots) 'run-steps' → attach a screenshot/evidence to a single run step (use the run-step ID from alm_get_run_steps) 'defects' → attach to a defect (screenshots, logs, evidence) 'tests' → attach to a test case 'test-sets' → attach to a test set 'requirements' → attach to a requirement entity_id: Numeric ALM ID of the entity. For 'run-steps', this is the run-step ID (not the run ID). file_path: Absolute path to the file on the machine running this server. Example: 'C:/reports/screenshot.png'

Returns: {"success": true, "entity_type", "entity_id", "file_path"}

Generic HPQL search across any ALM entity collection.

Use this for advanced queries not covered by the specific tools above.

Args: entity_type: ALM entity collection — e.g. 'defects', 'tests', 'requirements', 'test-sets', 'test-instances', 'runs', 'test-folders'. query: HPQL filter string (without braces). Examples: "status[Open];severity[4-Very High]" "name[login]" "owner[jsmith];creation-time[> '2026-01-01']" "owner[u1197976];parent-id[2400]" ← filter tests by folder + owner Leave empty to return all entities up to page_size. NOTE: For 'tests', use 'parent-id' to filter by folder — there is no 'subject' field. Combining 'parent-id' with multiple OR values (e.g. parent-id[1|2|3]) may cause HTTP 500 on some ALM servers; query each folder separately in that case. fields: Comma-separated ALM field names to include in the response. Example: 'id,name,status,owner,creation-time' For 'tests': valid fields include id,name,status,owner,parent-id, creation-time,subtype-id,description. 'subject' is NOT a valid field. page_size: Maximum records to return (default 100).

Returns: {"entity_type", "results": [...], "count": }

List all ALM domains and their projects accessible to the current user.

Use this to discover available domains and project names.

Returns: {"domains": [{"domain": "", "projects": ["", ...]}, ...]}