SauceLabs and saucectl reports

What is SauceLabs?

SauceLabs is a cloud-based testing platform that lets you run your web and mobile tests on hundreds of browsers, operating systems, and devices - without needing to set up and maintain all that hardware yourself.

Think of it as a giant virtual lab where:

• Manual testers can interact with real browsers and devices remotely.
• Automation engineers can run test scripts in parallel across many environments at once.
• QA managers can see detailed execution history, screenshots, and videos for every test.

Because SauceLabs runs in the cloud, you:

• Save time (no local environment setup)
• Test more combinations in less time (parallel runs)
• Get consistent test results, regardless of your machine

What is saucectl?

saucectl is SauceLabs’ command-line interface - a tool you run in your terminal that connects your local test framework (e.g., Cypress, Playwright, TestCafe) to SauceLabs’ cloud infrastructure.

With saucectl, you can:

• Trigger tests in the cloud directly from your command line or CI/CD pipeline
• Run tests in parallel across different browsers and devices
• Collect detailed test results in a JUnit XML format
• Attach useful metadata (browser, OS, SauceLabs session URL)

Why integrate SauceLabs with TestRail?

If you run your automated tests in SauceLabs, you already get detailed results: browser, platform, execution time, and direct links to the SauceLabs session.
 

If you also use TestRail to manage test cases and track results, you can import SauceLabs reports directly into TestRail, keeping all your manual and automated testing results in one place.

This integration:

• Automates results import from SauceLabs to TestRail
• Creates test cases automatically if they don’t exist
• Organizes runs by browser/platform
• Links directly to SauceLabs sessions for deeper debugging

Integrating results into TestRail

How the integration works

At a high level: SauceLabs runs your automated tests → creates a results file → TestRail imports and organizes those results.

Here’s what happens step-by-step:

1. Tests are run in SauceLabs
   You start your automated tests using saucectl.
   • Non-technical view: This is just the tool that sends your tests to SauceLabs’ cloud lab.
   • Technical view: saucectl uploads your test scripts to SauceLabs, triggers them in parallel across your chosen browsers/devices, and collects the results.
2. SauceLabs generates a JUnit XML report
   After the tests finish, SauceLabs produces a JUnit XML file.
   • This file is like a structured spreadsheet for automated test results.
   • It contains:
     • Which tests ran
     • Pass/fail status
     • Browser and OS info
     • Direct link to the SauceLabs test session
3. TestRail CLI parses the report
   You run the TestRail CLI command with the option --special-parser saucectl.
   • This tells TestRail to use its SauceLabs-specific parser, which understands the extra session info in SauceLabs’ JUnit reports.
   • Without this flag, the CLI might misinterpret the multi-browser results.
4. Results are imported into TestRail
   The CLI sends the parsed results to your TestRail project.
   • Each browser + platform combination becomes a separate TestRail test run (e.g., “Chrome 106 – Windows 11” and “Firefox 108 – Windows 11”).
   • If a test case doesn’t exist yet in TestRail, it’s created automatically.
   • The browser/OS info goes into the test run description.
   • The SauceLabs session URL is linked directly in each test result for quick access.

Quick visual flow

1. Run tests → saucectl run
2. Generate report → results.xml (JUnit format with SauceLabs extras)
3. Import results → trcli parse_junit --special-parser saucectl results.xml
4. View in TestRail → Runs grouped by browser/platform, with direct SauceLabs links

How SauceLabs results correspond to TestRail entries

When you import a SauceLabs JUnit XML report into TestRail using the --special-parser saucectl option, each part of the report is transformed into specific TestRail entities.
This lets you keep execution context (browser, OS, session link) while avoiding duplicate test case creation.

1. Browsers and platforms → Separate TestRail test runs

• In the JUnit XML, the <testsuite name> often includes the browser name and the test script file name.
• The <properties> block inside each testsuite includes:
  • browser → e.g., chrome 106 or firefox 108
  • platform → e.g., Windows 11
• In TestRail:
  • Each unique browser + platform combination becomes a separate test run.
  • The browser and platform are added to the test run title (e.g., Cross-browser automated tests (Chrome 106 - Windows 11)).

2. Test names → TestRail test cases

• In the XML, each <testcase name="..."> represents a specific automated test.
• In TestRail:
  • If a test case with the same name already exists in your project, TestRail updates it with the new result.
  • If it doesn’t exist, TestRail automatically creates it.
  • When the same test runs in multiple browsers, only one test case is created — but it will have separate results in each test run.

3. SauceLabs session URL → Link in TestRail results

• In the XML, the <property name="url"> contains a direct link to the test session in SauceLabs.
• In TestRail:
  • This URL is stored inside the result details for the corresponding test case.
  • You can click it to jump straight to SauceLabs to see video recordings, screenshots, logs, and detailed execution data.

4. Failures and errors → Result notes in TestRail

• In the XML, a <failure> element inside <testcase> contains:
  • type → the type of failure (e.g., “element not found”)
  • message → a short explanation
  • Inner text → stack trace or debug info
• In TestRail:
  • This information is added to the result comment, giving you immediate context on why the test failed.

5. Same session for multiple tests → Shared session link

• Sometimes multiple <testcase> entries are executed within the same SauceLabs session.
• In TestRail:
  • All related test results will have the same session URL in their result details.
  • This is useful when a session covers multiple small verification steps.

Example correspondence

Example JUnit XML snippet from SauceLabs

<testsuites tests="8">
  <testsuite name="Firefox - test_suite_1.cy.js" tests="1" time="48">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/7d7544f09a47428fb97ee53d1a5b1419"/>
      <property name="browser" value="firefox 108"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 1 Verify page structure" time="0.9450" classname="Verify page structure"/>
  </testsuite>
  <testsuite name="Firefox - test_suite_2.cy.js" tests="1" time="80">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/cbb864e049c645e1a96d56e953fe33f0"/>
      <property name="browser" value="firefox 108"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 2 Verify page structure" time="0.9670" classname="Verify page structure"/>
  </testsuite>
  <testsuite name="Chrome - test_suite_1.cy.js" tests="1" time="65">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/349cf779c0f94e649f7ea6ccc42e1753"/>
      <property name="browser" value="chrome 106"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 1 Verify page structure" time="0.7500" classname="Verify page structure">
      <failure type="element not found" message="Fail due to...">stacktrace...</failure>
    </testcase>
  </testsuite>
  <testsuite name="Chrome - test_suite_2.cy.js" tests="1" time="33">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/c0e3ddae1e104b86b940ed7e8026ff83"/>
      <property name="browser" value="chrome 106"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 2 Verify page structure" 
    time="0.7570" classname="Verify page structure"/>
  </testsuite>
</testsuites>

This report reflects the execution of the same project in two different devices - Firefox and Chrome - which can be identified on the testsuite element names, as per the image below. This means that the TestRail CLI will create two test runs in TestRail and add the corresponding test results. Each test run contains the same tests, which are Component 2 Verify page structure and Component 1 Verify page structure

TestRail will also include the browser and platform values in each test run description and the session url in the results of each test case.

CLI command to import SauceLabs reports

Run the following command from your terminal:

$ trcli -y \
>  -h https://INSERT-INSTANCE-NAME.testrail.io \
>  --project "My Project" \
>  --username INSERT-EMAIL \
>  --password INSERT-PASSWORD \
>  parse_junit \
>  --title "Cross-browser automated tests" \
>  --special-parser "saucectl" \
>  "./saucelabs-report.xml"

Parameters explained:

• <INSTANCE-NAME> → Your TestRail instance subdomain
• <EMAIL> / <PASSWORD> → TestRail login credentials
• "My Project" → TestRail project name
• "Cross-browser automated tests" → Test run title
• "./saucelabs-report.xml" → Path to your SauceLabs JUnit report

What happens in TestRail after import

• New test cases are created if they don’t exist.

• Test runs are grouped by browser/platform, e.g.
  • Cross-browser automated tests (Chrome)
  • Cross-browser automated tests (Firefox)

• Test run descriptions include platform and browser.
• Test case results include the SauceLabs session URL for quick navigation.

Tips & Troubleshooting

• Make sure SauceLabs is exporting JUnit reports (--reporter junit in your saucectl config).
• If multiple test cases run in the same SauceLabs session, they’ll share the same session URL in TestRail.
• If tests appear duplicated, check that your <testcase name> values are unique.
• For large test runs, import speed may improve if you split XML files by browser.

Next steps

• Check out the Cypress-saucectl sample project on GitHub for hands-on examples.
• Review the TestRail CLI documentation for additional parameters.
• Contribute improvements or raise questions via your team’s GitHub or TestRail support.