Rest APIs

The AIO Tests REST APIs provide programmatic integration with AIO Tests from any test framework in any language.

AIO Tests exposes REST APIs to create and manage test cases, cycles, sets, and test executions, retrieve project configuration and reporting data, and integrate automated testing workflows with external tools. The APIs provide the flexibility to seamlessly integrate your automated tests, written in any language, into AIO Tests, automate test management and execution processes, and maintain a unified view of both automated and manual testing from a single platform.

This guide explains the authorization mechanism and gives an overview of the available APIs.

In this documentation, you’ll understand:

The APIs are available at the following base URL: https://tcms.aiojiraapps.com/aio-tcms/api/v1/

Requests made to AIO Tests REST APIs must be authenticated with an Access Token. More information is available here.

AIO Tests APIs can be tried out on this Swagger page - AIO Tests Swagger
This page can be easily accessed by clicking on the Question button and selecting the ‘API Reference’ option from the drop-down.

Open

The authorization token generated can be used using the Authorize button on the Swagger page.

The APIs are available at following base URL: https://<jira_server_hostname>/<jira_context_path>/rest/aio-tcms-api/1.0/

For ex: If Jira is hosted on https://jira8.aiojiraapps.com, then REST APIs will be available at https://jira8.aiojiraapps.com/rest/aio-tcms-api/1.0/.

Requests made to AIO Tests REST APIs must be authenticated via Basic authentication or PAT authentication. More information is available here.

AIO Test APIs can be tried out via the Swagger page.
This page can be easily accessed by clicking on the Question button and selecting the API Reference from the drop-down menu.
APIs available in the Swagger documentation depend on the AIO Tests plugin version you have installed.

Open

Click on the Authorize button on the Swagger page to provide Jira Username and Password (Basic Authentication) to authenticate and try out the APIs.

The following AIO Tests APIs have been exposed. Details around each of these APIs can be found in Swagger documentation.

• Case Operations: Create, retrieve, update, and manage test cases, including their comments and attachments.

  • Get Case Comments: Get the comments associated with a specific case, including details such as the author and creation date.

  • Get Case Details: Get the details of a specific case, including its title, folder, tags, and other metadata. These details can be used to review or update the case.

  • Upload and Attach Files to Case: Upload and attach one or more files to a specific case.

  • Upload and Attach Files to Case RTF Fields: Upload and attach files to the Description or Preconditions fields of a case.

  • Upload and Attach Files to Case Step: Upload and attach one or more files to a specific test step within a case.

  • Upload and Attach Files to Case Step RTF Fields: Upload and attach files to the Step, Data, or Expected Results fields of a case step.

  • Create a New Case: Create a new test case by specifying the required case details.

  • Import Cases from Feature File: Import test cases from a feature file and create new cases or update existing tagged cases.

  • Update an Existing Case: Update the details of an existing case using the specified case information.

• Cycle Operations: Create, retrieve, update, and manage execution cycles and their associated data.

  • Delete a Cycle: Delete an existing cycle, with the option to empty it before deletion if it contains cases.

  • Get Cycle Details: Get the details of a specific cycle, including its name, folder, tags, and other metadata. These details can be used for reporting or updating the cycle.

  • Get Cycle Summary: Get the execution summary of a cycle, including effort, case counts, and run status distribution. These details can be used for reporting and tracking execution progress.

  • Upload and Attach Evidence to Cycle: Upload and attach execution evidence to a specific cycle.

  • Upload and Attach Files to Cycle RTF Fields: Upload and attach files to the Objective field or supported rich text custom fields of a cycle.

  • Create a New Cycle for Execution: Create a new execution cycle by specifying the required cycle details.

  • Create a New Cycle from Existing Sets: Create a new execution cycle from one or more existing sets and automatically add the eligible cases as runs.

  • Update an Existing Cycle: Update the details of an existing cycle using the specified cycle information.

  • Update Cycle State: Update the state of a cycle by marking it as Locked or Closed.

• Execution Management: Manage test runs, execution results, evidence, comments, and bulk execution operations within cycles.

  • Delete a Run: Delete a non-latest test run from a cycle.

  • Get Run Details by Run ID: Get the details of a specific test run in a cycle using its run ID.

  • Get Latest Run Details of a Case in a Cycle: Get the latest run details of a specific case in a cycle, including its status, effort, and execution information.

  • Get Cases Associated with Cycle: Get a paginated list of cases associated with a specific cycle, along with their latest run details.

  • Get All Runs Grouped by Cases Associated with Cycle: Get a paginated list of all cases in a cycle along with their associated runs.

  • Upload and Attach Evidence to Latest Test Run of Case: Upload and attach execution evidence to the latest run of a specific case in a cycle.

  • Upload and Attach Evidence to Case Runs: Upload and attach execution evidence to a specific test run.

  • Upload and Attach Evidence to Case Steps: Upload and attach execution evidence to specific steps within a test run.

  • Add an Existing Case to Cycle or Create a New Run: Add an existing case to a cycle or create a new run if the case already exists in the cycle.

  • Create a Batch Process to Import Automated Test Execution Results: Create a batch process to import automated test execution results from an XML file. The batch status can be tracked from the Cycles screen.

  • Add Multiple Existing Cases to Cycle, Add New Runs for Existing Cases, and Update Status of Already Created Runs: Add multiple existing cases to a cycle, create new runs when required, or update the results of existing runs in a single request.

  • Batch Call for Adding Multiple Existing Cases to Cycle, New Runs for Existing Cases, and Updating Status of Already Created Runs: Perform batch operations to add multiple cases to a cycle, create new runs, or update existing run results.

  • Update All Details of a Run: Update the complete details of a test run, including run and step statuses, comments, defects, and other execution information.

  • Add Existing Cases to Cycle, Add New Runs for Existing Cases, and Update Status of Already Created Runs: Add existing cases to a cycle, create new runs, or update existing run results in a single request.

  • Import Automated Test Execution Results from Results XML File: Import automated test execution results from a supported XML file.

  • Post a Comment to Run of a Test Case Identified by Run ID: Add a comment to a specific test run using its run ID.

  • Post a Comment to Latest Run of a Test Case: Add a comment to the latest run of a specific test case.

  • Bulk Update Fields of Test Runs: Update one or more fields across multiple test runs in a single request.

  • Batch Job for Bulk Update Fields of Test Runs: Create a batch job to update one or more fields across multiple test runs.

  • Clean Up Runs from a Cycle: Delete older test runs from a cycle while retaining the required execution history.

  • Reset All Data of a Run: Reset the status, comments, defects, and other execution data of a specific test run.

• Set Operations: Create test sets and manage the association of test cases with them.

  • Get Cases Associated with Set: Get a paginated list of cases associated with a specific set.

  • Add Multiple Existing Cases to Set: Add one or more existing cases to a set if they are not already associated with it.

  • Create a New Set: Create a new test set by specifying the required set details.

• Configuration: Retrieve project configuration, folders, statuses, custom fields, tags, and other metadata required for API operations.

  • Get Tags Defined by Your Team in Jira Project: Get a list of the Tags (ID and Name) defined within AIO Tests for a given Jira Project. These details can be used to attach specific tags while creating new cycles.

  • Get Custom Field Configuration: Get a list of the custom fields configured for the project. These details can be used while creating or updating supported entities.

  • Get Custom Field Types: Get a list of the supported custom field types available in AIO Tests.

  • Get Predefined Parameters: Get the predefined parameters configured for the project.

  • Get AIO Tests Specific Project Configuration: Get the AIO Tests project configuration, including case priorities, case types, statuses, automation statuses, and run statuses.

  • Get Case Automation Status Configuration: Get a list of the available Case Automation Statuses configured for the project. These status IDs can be used while creating or updating cases.

  • Get Case Folder Tree Structure: Get the folder hierarchy for test cases. These folder IDs can be used while creating or updating cases.

  • Get Cycle Folder Tree Structure: Get the folder hierarchy for cycles. These folder IDs can be used while creating or updating cycles.

  • Get Case Priority Configuration: Get a list of the available Case Priorities configured for the project. These priority IDs can be used while creating or updating cases.

  • Get Run Status Configuration: Get a list of the available Run Statuses configured for the project. These status IDs can be used while updating test runs or interpreting cycle summary results.

  • Get Run Step Status Configuration: Get a list of the available Run Step Statuses configured for the project. These status IDs can be used while updating test run steps.

  • Get Test Script Type Configuration: Get a list of the available Test Script Types configured for the project.

  • Get Set Folder Tree Structure: Get the folder hierarchy for sets. These folder IDs can be used while creating or updating sets.

  • Get Case Status Configuration: Get a list of the available Case Statuses configured for the project. These status IDs can be used while creating or updating cases.

  • Get Case Type Configuration: Get a list of the available Case Types configured for the project. These type IDs can be used while creating or updating cases.

  • Create New Tags for Jira Project: Create one or more new tags for a Jira project and retrieve their IDs and details.

  • Get or Create Case Folder Hierarchy: Get an existing case folder hierarchy or create it if it does not exist. The returned folder ID can be used while creating new cases.

  • Get or Create Cycle Folder Hierarchy: Get an existing cycle folder hierarchy or create it if it does not exist. The returned folder ID can be used while creating new cycles.

• Case Listing: Retrieve, search, and export test cases based on the specified criteria.

  • Get Cases: Get a paginated list of test cases.

  • Export BDD/Gherkin Cases into Feature Files: Export BDD/Gherkin test cases as zipped feature files, with optional grouping by folder, requirement, or tag.

  • Search Cases: Search for test cases based on the specified search criteria and retrieve the matching results.

• Batch: Monitor the status of asynchronous batch operations initiated through the APIs.

  • Get Batch Status Information: Get the current status and progress of an automation import batch.

• Cycle Listing: Retrieve and search execution cycles based on the specified criteria.

  • Get Cycles: Get a paginated list of execution cycles.

  • Search Cycles: Search for execution cycles based on the specified search criteria and retrieve the matching results.

• Set Listing: Retrieve and search test sets based on the specified criteria.

  • Get Sets: Get a paginated list of test sets.

  • Search Sets: Search for test sets based on the specified search criteria and retrieve the matching results.

• Traceability: Retrieve the traceability between Jira requirements and their associated test cases and executions.

  • Get Traceability Information for a Requirement: Get the test cases associated with a specified Jira requirement, along with their latest run details.

• Migration: Import historical cycles and test runs into AIO Tests while preserving their original execution dates.

  • Migrate Runs to AIO Tests: Import historical test runs into AIO Tests by creating backdated runs for existing cycles and cases.

  • Migrate Cycle Details: Create a new backdated cycle by specifying its historical creation date and other cycle details.

  • Migrate Runs to AIO Tests in Bulk: Import multiple historical test runs into AIO Tests in a single request by creating backdated runs for existing cycles and cases.

• Attachment: Retrieve attachments associated with supported AIO Tests entities using their attachment IDs.

  • Retrieve Attachment Using Attachment ID: Retrieve an attachment associated with a supported AIO Tests entity using its attachment ID.

You can also use the below sample Postman Collection to try out the Public APIs.
Download and Import the collection into Postman.

Open

In the Postman collection, few collection-level variables have been defined. Either update the variables directly in the requests or navigate to Edit Collection and update the variable values as per your Jira instance values (Refer to the below screenshot).

Open

With the introduction of the Cross-Linking feature (release 2.1), Cases from different Projects can be added to a Cycle. Users who do not have access to a project, will not be able to access the Case / Run from that project in the Cycle.

To indicate the access user has on different Entities - Case / Cycle & Run, the Permission object will be returned in response.

Sample Permission object is below:

• Permission object has value and error properties.

• Value is a bit map where in bits from right to left represent the Delete, Write & Read permissions.
  7 - Full access (Delete, Write, Read)
  3 - Only Write and Read
  1 - Only Read
  0 - No permission

• Error is an enum indicating why the user does not have access over the cycle.
  The error can be one of:

  • EVALUATION_FAILED- There was an error while evaluating the permission value.

  • JIRA_PROJ_NO_ACCESS- The user does not have access to the entity as the User does not have permission on the entity’s Project.

  • AIO_TESTS_DISABLED_PROJ- The user does not have access to the entity as AIO Tests have been disabled for the entity’s Project.

  • AIO_TESTRUN_REFSTEP_NO_ACCESS- The user does not have access on the Run as one of the Referenced Step Cases is not accessible.

• If a user has permission (the error value is null), then an error will not be returned in the response.

The below table shows the Permission Values and Delete / Write / Read access it indicates.
If the bit is ON (having value 1), it means the user has permission to perform those operations.

 The below table shows the Run permissions based on the corresponding Cycle and Case access.

The user who has Read-only access to Run, will not be able to change the status of a run, but would be able to view its data. On trying to update such a Run using the API will return a 4xx response.

For further queries and suggestions, please feel free to reach out to our customer support service via help@aiotests.com.