Skip to main content

TestRail Integration

The TestRail integration allows you to connect Ranorex Studio and TestRail. 

  • Import and export TestRail test suites and test cases.
  • Synchronize changes between Ranorex Studio and TestRail.
  • Run tests in Ranorex Studio (or via CI) and automatically export results to TestRail when reporting is enabled.
  • Optionally, upload evidence (screenshots, Ranorex reports) to TestRail as part of reporting.

Getting started

Before you connect Ranorex Studio to TestRail, confirm that TestRail is configured correctly. Refer to the relevant sections of the Integrating with Ranorex for more information.

Configuring TestRail

Note: You need Admin privileges in TestRail to change the settings in this section.

Enable API

TestRail’s API needs to be enabled so Ranorex Studio and TestRail can interact.

  1. In TestRail, go to Administration > Site Settings > API.
  2. Enable Enable API.

Note: You do not need an active API key for this integration; the API can be used with a username and password.

Permissions

Being an admin gives you the permissions to set up the integration (to manage all the Add/Edit Cases and Sections, Suites, Add/Edit Test Results, Add/Edit Attachments, Add/Edit Runs & Plans). Other users will need to be permitted these actions. 

Depending on how you use the integration, the TestRail user account must have certain permissions. 
To set them, go to Administration > Users & Roles and create a role with the appropriate permissions or change the permissions of an existing role. 

  • Import into Ranorex Studio: No permissions are required.
  • Export to existing projects: Add/Edit Cases & Sections, Suites.
  • Export to new projects: You need to be an admin on TestRail.
  • Report results to an existing TestRail run: Add/Edit Test Results, Add/Edit Attachments.
  • Report results to a new TestRail run: Add/Edit Runs & Plans, Add/Edit Test Results, Add/Edit Attachments.

Automation Type field

Ranorex Studio imports and synchronizes only TestRail cases that are marked as automated for Ranorex.

  • TestRail 5.5 and later: The Automation Type drop-down field is already present by default. Simply set it to Ranorex.
  • TestRail 5.4 and earlier: You will need to add a custom field to the user interface for importing and exporting to work correctly.
  1. Go to Administration > Customizations > Case Fields
  2. Add a field with the following values:
    • Label: Automation Type
    • System Name: automation_type
    • Type: Dropdown
  3. Click Add Projects & Options and specify Ranorex as Option 1. Click the Selected Projects tab and apply the field to your projects.
  4. Under the Configure Options, ensure Ranorex id is 1, and the Default Value is None. 

Required custom fields

If your TestRail project uses required custom fields, ensure required fields have default values. Otherwise, export/sync can fail because Ranorex Studio cannot infer which value to populate.

Fixing this error is explained in  Importing, exporting, synchronizing.

Synchronization modes

Ranorex Studio supports two synchronization modes:

  • Manual synchronization: You trigger synchronization from the integration UI when you decide it’s needed.
  • Automatic synchronization: Ranorex automatically pushes run results to TestRail after execution when enabled.

Automatic synchronization can be enabled:

  • From the TestRail integration settings, or
  • In the wizard at the end of an import (Import complete).

For details, see:

  • Running tests and reporting to TestRail (how reporting works)
  • Importing, exporting, synchronizing (what is synchronized and when)

TestRail run naming (to prevent duplicates)

When Ranorex creates or updates runs in TestRail, it uses a standardized run name format so you can distinguish runs clearly and avoid confusing duplicates:

Format
[Ranorex Test Suite Name] - [Ranorex Test Run Timestamp] - [Environment/Configuration]

Example
Ranorex_Smoke_Chrome - 2025-06-12_16-26-32 - QA_Environment

Note: TestRail run titles have a maximum length of 250 characters. If the generated name exceeds this limit, the name is truncated to 250 characters. Truncation preserves the beginning of the title so the most important information remains visible.

TestRail Wizard

  1. In Ranorex Studio, open the solution you want to work with.
  2. Go to Tools > TestRail integration > Start TestRail wizard.
  3. In Connect to TestRail, enter:
    • Server address
    • Credentials
  4. Click Sign in.

Tip: The server address applies to both TestRail on-premises and TestRail Cloud. You can copy it from your browser’s address bar.

After signing in, the wizard takes you to Import/Export, where you can import, export, and set up the connection. See Importing, exporting, synchronizing.

Next steps

Was this article helpful?
Powered by Zendesk