⚠️ Warning: This integration setup is for TestRail Cloud only (e.g., https://<MY_DOMAIN>.testrail.io). If you are using a TestRail Server or On-Premise instance, please consult your network administrator.
1. How does SQAI Suite Leverage This Integration?
Connecting to TestRail allows SQAI to integrate directly into your testing management workflow:
Centralized Test Creation: Allows SQAI to generate new, high-quality test cases directly within your designated TestRail Project and Section.
Streamlined Workflow: Eliminates the manual effort of transferring generated test assets into your Test Management Tool (TMT).
Traceability: Enables the efficient management and tracking of AI-generated test assets alongside your existing test suite.
2. Information Required from Your TestRail Account
To establish a secure, plug-and-play connection, we require five specific pieces of information, most of which can be found in your browser URL or user settings.
Required Detail | Explanation | How to Find It |
Instance URL | The base URL of your TestRail cloud instance. |
|
Username | The email address of the user who created the API Token. | Your login email address. |
API Token | A unique, private token generated in your user settings for API authentication. | See Section 3. |
Project ID | The numerical ID of the Project where test cases will be created. | See Section 2.1 (Found in the URL). |
Section ID | The numerical ID of the specific Section within the Project where test cases will be placed. | See Section 2.1 (Found in the URL). |
2.1 Retrieving the Project ID and Section ID
Log into TestRail and navigate to the Test Cases section of your desired project.
The Project ID (
p=...) is visible in the URL when viewing any project overview.
Click on the specific Section you wish to integrate (e.g., "AI generated"). The Section ID (
section_id=...) will be visible in the URL after clicking the section.
3. Setting up the API Token
TestRail requires a combination of your Username (email) and the API Token for authentication.
Step 1: Navigate to My Settings
Click My Settings (often found in the dropdown menu in the top right corner).
Step 2: Generate API Token
In the "My Settings" area, navigate to the API Keys tab .
Click Add Key.
Provide a clear name (e.g., "SQAI Integration") .
Click Generate Key
Crucially: The generated key is only displayed once. Store this key in a secure location before clicking Add Key.
⚠️ Note: The secret required for authentication in SQAI Suite will be saved as username:token where the username is your email address.
6. Save the settings
4. Entering Details in SQAI Suite
Once you have secured your API Token and gathered the necessary IDs, you can complete the setup in the SQAI Suite platform.
Step 1: Navigate to Integrations Go to your SQAI Suite settings and select the Integrations page. Find and select the TestRail configuration.
Step 2: Enter Details Insert the following details into the corresponding fields:
URL (Your TestRail Instance URL)
Username (The e-mailaddress of the Testrail user who generated the API Token)
API Token
Expiration Date (Optional)
Project ID
Section ID
Step 3: Save and Confirm Click "Save Configuration." If the set-up is successful, you will receive a success message and see a green indicator next to your integration.
5. Troubleshooting TestRail Integration
If SQAI reports an error or fails to connect, use this checklist to quickly identify and resolve the most common issues related to access.
Problem | Cause | Solution |
Connection Failed: "Unauthorized" or "401" | A. Invalid API Key/Username Combination: The API Token or Username (email) was copied incorrectly. Or the format is not correct. | Verify Credentials: Re-check the Username (email) and regenerate the API Token if necessary, ensuring the token is current. Format should be |
Invalid Resource: Cannot Find Project/Section | B. Incorrect ID: The Project ID or Section ID contains a typo or is outdated. | Double-Check URL: Verify the IDs by navigating back to the TestRail interface and confirming the numbers in the URL (Section 2.1). |
SQAI Connects, But Cannot Write | C. User Permissions: The user associated with the API Key does not have Write permissions for the specific project or section. | Check User Role: Ensure the user who owns the API Key has the necessary role (e.g., Lead or Admin) within the targeted TestRail Project. |
Token Expired | D. Token Visibility: The API key was generated but not copied immediately. | Generate New Key: The key is only displayed once; you must generate a new key from the API settings and update the configuration in SQAI Suite. |