How to Integrate qTest with Test Automation

To integrate qTest with test automation, first decide where tests should execute: on qTest-managed Automation Host agents, in Jenkins or Bamboo, or in a custom runner using Universal Agent or the qTest API. Enable Automation Integration in the target project and map the automation statuses to qTest statuses before submitting results. One key distinction: the Jenkins and Bamboo integrations collect and submit test results; they do not execute tests. The documented CI report format is JUnit XML.

Use qTest scheduling when you want qTest to dispatch work to registered agents. Use a CI plugin when tests already run in Jenkins or Bamboo and you want their results linked to qTest. Choose Universal Agent or the API for scripted or bespoke workflows. Confirm the documentation version, deployment, supported framework or parser, and license entitlement for your qTest instance before implementation.

Choose an integration route

Route	Where tests run	Best fit	Check before choosing
qTest scheduling / Launch	Machines with registered Automation Host and agents	Teams that want qTest to schedule jobs and show execution results	Project integration settings, agent and framework support, deployment and license
Jenkins or Bamboo plugin	Inside the CI build	Teams already running tests in CI	JUnit XML output, status mapping, plugin compatibility and credentials
Universal Agent	A scripted workflow on the agent host	Custom frameworks or explicit setup, checkout, execution and report steps	Automation Host 2.1.0 or later and the applicable parser or agent instructions
qTest API	Your external runner or integration service	Bespoke result submission and integration logic	API specification for your qTest release, token handling and enabled Automation Settings

Compare routes by execution ownership, report format and parser, status mapping, framework support, scheduling needs, permissions, deployment model and current license entitlement. Availability can differ between SaaS and on-premises installations and between packages.

Before connecting a runner

Identify the qTest project, release and test cycle that should receive results.
Confirm whether tests will run on qTest agents, in CI, or in a custom runner.
Ask a Project Admin to enable Automation Integration in the project and map source statuses such as passed, failed and skipped to qTest values. Do not assume the names or meanings match automatically.
Check the chosen integration’s report format, parser and version requirements.
Use the documentation matching your qTest version and deployment. Store tokens in the execution system’s credential store, not in source code.

Set up qTest-managed scheduling

In this pattern, qTest schedules automation test runs for registered hosts and agents. Agents poll for work, execute it, then send logs and results to qTest Manager.

Enable the project integration. In the project’s Automation Settings, activate Automation Integration, map the automation statuses to qTest Manager statuses, and save. A Project Admin permission is required.
Install Automation Host. Download and install qTest Automation Host on each machine that will run tests. Once it is running, the host registers with qTest.
Create an Automation Agent. In qTest Launch, create an agent and select a supported agent or framework workflow. Use Universal Agent when you need a flexible scripted workflow; it requires Automation Host 2.1.0 or later.
Create automation test runs. In qTest Manager, create or configure the runs that should be scheduled.
Schedule and verify. Schedule the runs, then review their status and execution logs in the relevant scheduling or Launch views. Confirm that results land in the intended project, release and cycle and that statuses map as expected.

qTest Launch manages hosts, agents and scheduling. Tricentis documents Tosca DEX as the native route for Tosca execution in Launch; non-Tosca runs are distributed across selected agents. Verify current framework support and entitlement for your instance.

Send Jenkins or Bamboo results to qTest

In this route, the CI job runs the tests and produces a report. The qTest integration collects the report and submits results; it is not a test runner. The documented supported report format is JUnit XML.

Enable CI integration. Activate CI Tool Integration for each qTest project that should receive results. This also activates Automation Integration, so configure the status mapping.
Install and configure the plugin. Install the appropriate qTest plugin in Jenkins or Bamboo and configure its connection to the target qTest project.
Add credentials securely. Obtain the relevant integration or API token from qTest resources and store it in the CI system’s credential-management feature. qTest API, Jenkins and Bamboo tokens automatically expire when the associated user password is reset; re-add or verify credentials after a reset.
Publish JUnit XML. Configure the test job to produce JUnit XML and make that report available to the qTest plugin. If a Jenkins framework does not generate JUnit XML, Jenkins can use the xUnit plugin to publish JUnit XML-compatible results.
Run a representative build. Check that the expected test runs, statuses and logs appear in qTest Manager and are associated with the intended project, release and cycle.

The documented qTest Bamboo plugin does not support Bamboo Specs. Check the current Tricentis integration documentation for your qTest release before relying on a particular plugin workflow.

Connect a custom framework with Universal Agent

Universal Agent supports scripted workflows that prepare the environment, obtain source code, execute tests and submit results to qTest Manager. The documented overview requires Automation Host 2.1.0 or later. Consult the Universal Agent instructions for the agent creation process, supported framework integrations, code examples, parsers and custom parser development. Parser behavior is a deployment detail; do not assume that a report from an arbitrary framework will be understood without a supported parser or conversion step.

Enable Automation Integration and map statuses in the qTest project.
Install a compatible Automation Host and configure the Universal Agent workflow.
Prepare dependencies and test data, then check out the intended source revision.
Run the test command and produce a report supported by the configured parser.
Submit results to qTest Manager and inspect the returned run, statuses and logs.

Keep environment setup, source checkout, execution and report submission as distinct steps in the script. This makes it easier to diagnose whether a failure happened before the tests ran, during execution, or while results were being submitted.

Build a custom integration with the qTest API

The API route gives an external runner control over result submission. qTest resources use HTTPS request URIs, standard HTTP methods, headers and bodies. External applications authenticate with a qTest authentication token. Automation-related API parameters are invalid when the project’s Automation Settings are disabled.

There is no single safe, runnable API request that fits every qTest release and deployment: endpoint paths, required fields and resource relationships depend on the applicable API specification. Use the specification for your target instance rather than copying an endpoint from another release.

Enable project Automation Integration and set status mappings.
Read the API specification for your qTest version and identify the resources and operations for your workflow.
Request an authentication token using the documented mechanism. Keep it in a secret store and send it only over HTTPS.
Construct the documented request with the required project, test run and result data. Map all source statuses explicitly.
Handle non-success HTTP responses, timeouts and token expiration; log a correlation or run identifier without logging the secret.
Verify in qTest Manager that each result is attached to the intended run and that retries do not create duplicate or misleading results.

For API, Jenkins and Bamboo integrations, remember that a user password reset automatically expires the related tokens according to the qTest resources documentation. Plan credential renewal and monitor for authentication failures.

Validate the integration

Run a small representative suite with at least one passing and one failing test, plus any skipped or framework-specific statuses you use.
Confirm that qTest receives the expected run, test names, statuses and available logs.
Check the project, release and cycle association.
For CI, verify the JUnit XML path and that the report exists before the qTest collection step.
For scheduled execution, confirm the host and agent are registered and polling the intended schedule.
For custom workflows, distinguish test failures from setup, parser, network and submission errors.

Troubleshooting

Symptom	Likely cause	What to check or fix
Automation parameters or result submission are rejected	Automation Integration is disabled, or the account lacks permission to configure it	Have a Project Admin enable the project setting and save status mappings.
Results appear with the wrong status	Source framework statuses do not map to the intended qTest statuses	Review Automation Settings mappings, including skipped and custom states, then submit a representative run again.
Jenkins or Bamboo build succeeds but qTest has no results	The plugin collects reports but does not run tests; the report may be absent, in the wrong location or not JUnit XML	Ensure the CI job executes tests, generates JUnit XML and exposes it to the configured plugin step.
Jenkins framework report is not accepted	The framework does not emit the documented JUnit XML format	Configure JUnit XML output or use Jenkins xUnit to publish compatible results.
Authentication suddenly fails	A token expired, including after a user password reset	Re-verify or replace the API, Jenkins or Bamboo token in the credential store.
Scheduled run does not start	Host or agent is not installed, registered, available, or compatible with the chosen workflow	Check Automation Host and agent status, framework support, schedule selection and version requirements.
Universal Agent runs tests but results do not appear	Report parser mismatch, unsupported report, or failed submission step	Check the configured parser and its instructions, inspect submission output, and verify Automation Settings are enabled.
API call returns an error or results attach to the wrong run	Request differs from the target release specification, uses incorrect identifiers, or omits required fields	Recheck the API specification for the instance, request body, project/run identifiers and token scope.
Setup instructions do not match the instance	SaaS and on-premises documentation or product versions differ	Use documentation for the actual deployment and release; confirm entitlement with the qTest administrator.

Performance, reliability and cost considerations

Execution time: qTest scheduling distributes work to selected agents; capacity depends on the available hosts and agents. CI execution time remains governed by the CI workers and test suite. Avoid treating report collection as a way to parallelize tests.
Reliability: Make report generation and result submission observable steps. Preserve enough logs to tell test failures from infrastructure or reporting failures. For custom API clients, handle transient network errors and authentication expiry according to the target API’s guidance.
Retries: Before retrying a failed submission, determine whether the first request created a run or result. Use the API’s documented identifiers and idempotency behavior; do not assume retries are duplicate-safe.
Credentials: Store tokens in CI or runner secret management, restrict access, and include password-reset token expiry in rotation procedures.
Cost and entitlement: Check your qTest contract and deployment for access to Launch, agents and integrations. The reviewed documentation does not establish a universal price or entitlement across deployments.

Or skip the browser setup

If the workflow also needs website screenshots, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Use a GET request to capture a URL as an image or PDF; the qTest integration choices above remain responsible for test execution and result reporting.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for configuration and options. Cookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Can qTest run automated tests?

Yes, through qTest-managed scheduling with registered Automation Host machines and agents. The Jenkins and Bamboo integrations instead collect results from tests run by the CI job.

How do I send Jenkins test results to qTest?

Enable CI Tool Integration for the project, configure the qTest Jenkins plugin and credentials, then publish JUnit XML from the CI job for the plugin to collect.

Can I connect a framework that has no qTest plugin?

Use Universal Agent for a scripted workflow with a compatible parser, or build a custom integration using the qTest API specification for your release.

Do statuses map automatically?

Configure the project’s automation status mappings. Source and qTest status names should not be assumed to match.

Does the same setup apply to SaaS and on-premises qTest?

Not necessarily. Follow the documentation that matches the instance’s deployment and release.