Usage examples

Updated May 30, 2025 14:13

The TestRail CLI has multiple features to support the most varied needs when it comes to managing your automated test results upload and enriching these results with more data.

Enriching test results using the CLI

When submitting test results, TestRail enables adding various types of data in various fields. For instance, you may want to upload a screenshot as an attachment, add a text comment to your result or use custom result fields to store data in a more structured way. Using the TestRail CLI, you can do all of this, in multiple ways. See below options that you can invoke using the CLI:

Result fields
- Name: Equal to or prefixed with --result-fields
- Value: Using the pattern field_name:field_value

As an example, to add the same value for a field of all results, you can pass the value directly in the command line by using the --result-fields argument one or more times (see below):

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --result-fields "version:1.2" \
>    --result-fields "custom_environment:qa02" \
>    -f "results.xml"

Enriching test results within automation projects

If you need to add different values for each result, you can also achieve that by adding properties to the JUnit report under each test case. Using this technique, you can not only enrich your results with fields data, but also add comments and attachments.

Reference a sample project using Java and JUnit 5 that implements the TestRail JUnit Extensions Project to programmatically add test result comments and customizable attributes when integrating test results into TestRail.

Attachments
- Name: Equal to or prefixed with testrail_attachment
- Value: Path to the file to be uploaded

@ExtendWith(TestRailTestReporterParameterResolver.class)
class SumTests {
    @Test
    @DisplayName("Add Two Numbers With Decimals")
    void AddTwoNumbersWithIntegers(TestRailTestReporter customReporter) {
        // Sets the "testrail_attachment" property on the report with a path to a file to be uploaded with the test result
        customReporter.setProperty("test", "sample_reports/testrail.jpg");
        assertEquals(3, 2+1, "2+1 should equal 3");
    }
}

Comments

Name: Equal to or prefixed with testrail_result_comment
Value: Text to append to the comment field

@ExtendWith(TestRailTestReporterParameterResolver.class)
class SumTests {
    @Test
    @DisplayName("Add Two Integers")
    void AddTwoNumbersWithIntegers(TestRailTestReporter customReporter) {
        // Sets the "testrail_attachment" property on the report with a path to a file to be uploaded with the test result
        customReporter.setProperty("testrail_result_comment", "positive case integer addition scenario");
        
assertEquals(3, 2+1, "2+1 should equal 3");
    }
}

Note: To successfully submit Result Steps, the target Test Case's template must have the step_results field active. By default, only the "Test Case (Steps)" template includes this Results Field, but other templates can be customized to include the "Test Case (Steps)" as well. More information on Test case templates can be found here.

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="0.05" name="tests.LoginTests">
    <properties><property name="setting1" value="True"/></properties>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
     <properties>
         <property name="testrail_attachment" value="path_to/logs.log"/>
         <property name="testrail_attachment" value="path_to/screenshot.jpg"/>
         <property name="testrail_result_field" value="version:1.2"/>
         <property name="testrail_result_field" value="custom_environment:qa02"/>
         <property name="testrail_result_comment" value="Finding 1"/>
         <property name="testrail_result_comment" value="Finding 2"/>
         <property name="testrail_result_step" value="passed: Insert login credentials"/>
         <property name="testrail_result_step" value="failed: Click submit"/>
         <property name="testrail_result_step" value="untested: User should be logged in"/>
     </properties>
    </testcase>
  </testsuite>
</testsuites>

Enriching test case creation

If you are using a code-first approach with automatic test case creation, you can also enrich your test cases with data on any field. When submitting test results, TestRail enables adding various types of data in various fields. For instance, you may want to upload a screenshot as an attachment, add a text comment to your result or use custom result fields to store data in a more structured way. Using the TestRail CLI, you can do all of this, in multiple ways.

To add the same value for a field of all test cases, you can pass the value directly in the command line by using the --case-fields argument one or more times.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --result-fields "version:1.2" \
>    --result-fields "custom_environment:qa02" \
>    -f "results.xml"

If you need to add different values for each test case, you can also achieve that by adding properties to the JUnit report under each test case, using the following convention:

Case fields
- Name: Equal to or prefixed with testrail_case_field
- Value: Using the pattern field_name:field_value

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="0.05" name="tests.LoginTests">
    <properties><property name="setting1" value="True"/></properties>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
     <properties>
         <property name="testrail_case_field" value="refs:STORY-1"/>
         <property name="testrail_case_field" value="custom_preconds:My preconditions"/>
     </properties>
    </testcase>
  </testsuite>
</testsuites>

Keeping new test cases in one section

If you are using a code-first approach with automatic test case creation, you may want these to be segregated from other test cases in the test cases repository. To keep all your new test cases together under one section, you can make use of the --section-id argument. By doing so, all your automated suites and test cases will be created under the specified section.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --section-id "213" \
>    -f "results.xml"

Adding a test run under a milestone

Milestones are a great way to organize your testing efforts. You can use them to aggregate test runs or plans with a common purpose. If you want your automated test runs created under a milestone, you can pass the --milestone-id argument and the TestRail CLI will create the test run under the specified milestone.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --milestone-id "57" \
>    -f "results.xml"

You should now see the new test run under the specified milestone. This is one way to keep track of your automated test results in one place.

Adding a test run under a test plan

Test plans also aggregate test plans with a common purpose, with the plus of allowing you to specify certain execution configurations. In example, you can have the same set of tests being executed using different browsers and have that information showing on your test plan. If you want your automated test runs created under a test plan, you can pass the --plan-id argument and the TestRail CLI will create the test run under the specified test plan. Although optional, on top of that, if you want to associate the test run with a certain configuration, you can also pass the --config-ids argument with a comma separated list of configuration IDs.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --plan-id "57" \
>    --config-ids "25,34" \
>    -f "results.xml"

You should now see the new test run under the specified test plan. This is another way to keep track of your automated test results in one place.

Updating test results on existing test run

Imagine you already ran the TestRail CLI and you have your automated test results on TestRail, but some of the tests failed and you want to rerun those and update the existing test run with the new results. In order to do so, you just need to pass the --run-id argument and the TestRail CLI will update the test run with that id.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --run-id "32" \
>    -f "results.xml"

You should now see the new test result on the test details panel. This is one way to keep track of your automated test results under the same test run.

Test result updated

Closing the test run

If you want to immediately close your newly created test run, you can simply pass the --close-run argument and the TestRail CLI will perform that action after all the results have been added. This is useful if you don’t want to allow changes to be made to the results after the run has finished.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --close-run \
>    -f "results.xml"

You can find your test run under the Completed test runs section.

Test run closed

Results elapsed time in milliseconds

For TestRail versions 5.5 and above, it is possible to submit the test results elapsed time in milliseconds (i.e.: 0.001s). The default TestRail CLI behavior will round the time to seconds in order to work for every TestRail version. If you are running one of the versions that supports milliseconds and want to see the elapsed time in your result using milliseconds, you can pass the --allow-ms argument.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --allow-ms \
>    -f "results.xml"

In your test results, you should now see the elapsed field using milliseconds.

Using config files to store alternate configurations

Quickly and easily submit results to different instances or projects, use different credentials, or other preset parameters in your commands by using an alternate config file. The configuration file will be written in YAML format, named config.yml, and stored in the same directory as the TRCLI executable file, unless otherwise specified. Environment variables can also be used. If a configuration file is referenced in the command, all parameters within the configuration file will override the environment variables. Any parameters specified in the command will override the config file.

The following example displays the use of an alternate configuration file that stores users credentials:

host: https://INSERT-INSTANCE-NAME.testrail.io 
project: TRCLI Test
username: username@domain.com 
password: passwordORapikey
title: Automated Tests Run

$ trcli -y \
>    --config alternate_config.yaml \
>    parse_junit \
>    -f "results.xml"

Creating new test runs

When a test run MUST created before using one of the parse commands, use the add_run command. For example, if tests are run across parallel, independent test nodes, all nodes should report their results into the same test run. First, use the add_run command to create a new run; then, pass the run title and id to each of the test nodes, which will be used to upload all results into the same test run.

$ trcli add_run --help
TestRail CLI v1.9.12
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli add_run [OPTIONS]

Options:
  -title               Title of Test Run to be created or updated in
                       TestRail.
  --suite-id           Suite ID to submit results to. [x>=1]
  --run-description    Summary text to be added to the test run.
  ---milestone-id      Milestone ID to which the Test Run should be
                       associated to. [x>=1]
  --run-assigned-to-id The ID of the user the test run should be assigned
                       to. [x>=1]
  --run-include-all    Use this option to include all test cases in this test run.
  --case-ids           Comma separated list of test case IDs to include in
                       the test run.
  --run-refs           A comma-separated list of references/requirements
  -f, --file           Write run title and id to file.
  --help               Show this message and exit.