Creating and Managing Test Runs in QTest: A Practical Guide

Why Test Runs Matter

A Test Run in QTest is the execution container that links a set of test cases to a specific testing effort. It gives you a single view of who owns the run, what the current status is, and how the effort is progressing. Without a run you can’t track execution, generate reports, or trigger CI/CD pipelines.

Desired Outcome

By the end of this article you’ll be able to:

• Create a new Test Run from a Test Suite.
• Assign users or teams to the run.
• Execute test cases and see real‑time status updates.
• Generate and export a run report.
• Trigger a run via the REST API and ingest results.
• Recover from accidental deletions or mis‑assignments.

Prerequisites

• QTest instance (v3.7 or later) with a valid project.
• Login with a role that includes Test Manager permissions.
• Existing Test Suite populated with test cases.
• Optional: API key or OAuth token for REST calls.

Step‑by‑Step Procedure

1. Create a Test Run

1. Navigate to Test Suites in the project menu.
2. Select the suite you want to run.
3. Click Create Run (top right).
4. In the dialog:
• Run Name – give a descriptive title.
• Run Description – optional notes.
• Owner – choose a user or team.
• Execution Mode – Manual, Automated, or Hybrid.
5. Click Save. The run appears in the Runs list.

2. Assign Execution Ownership

After creation you can re‑assign:

1. Open the run detail page.
2. Click Edit next to Owner.
3. Select a different user or a team from the dropdown.
4. Save changes. The new owner receives a notification email.

3. Execute Test Cases

Execution updates the run’s status graphically:

1. In the run view, click a test case row.
2. Choose a status (Pass, Fail, Blocked).
3. Add optional comments.
4. Click Submit. The status appears in the run’s summary bar.
5. Repeat for all cases.

Note: Unsaved status changes are not persisted. Always click Submit before leaving the page.

4. Generate a Run Report

1. In the run view, click Generate Report.
2. Choose format: PDF or CSV.
3. Optional: select metric filters (e.g., only failed cases).
4. Click Generate. Download the file.

Verify the report by opening it and checking that the number of passed/failed cases matches the run summary.

5. Trigger a Run via the REST API

Automated pipelines can start runs and import results. The following example uses cURL and an API token.

# Create a run via API
curl -X POST https://your-qtest-domain/api/v2/runs \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Regression Run 2026-10-14",
  "description": "Automated trigger from CI pipeline",
  "suite_id": 12345,
  "owner_id": 67890,
  "execution_mode": "Automated"
}'

Check the response: a JSON object containing the new run’s id. Use that ID to post execution results later.

6. Import Execution Results

# Submit a test result
curl -X POST https://your-qtest-domain/api/v2/runs/RUN_ID/results \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
  "test_case_id": 54321,
  "status": "Pass",
  "comments": "Automated run succeeded"
}'

After posting, refresh the run page in the UI to see the updated status.

Expected Checks

• Run appears in the Runs list with the correct name and owner.
• Test case status changes are reflected immediately after Submit.
• Run report counts match the number of executed cases.
• API responses contain expected fields (e.g., id, name, status).
• No rate‑limit errors (HTTP 429) when creating many runs; if encountered, reduce batch size.

Recovery Options

• Accidental Deletion of a Run: Runs are soft‑deleted and recoverable within the UI via the Archive panel. Open the Archive, select the run, and click Restore.
• Mis‑assigned Owner: Re‑edit the owner field as described in Step 2.
• Lost API Token: Regenerate a token from the API Keys page and update scripts.
• Excessive API Calls: Implement exponential back‑off or pagination; consult QTest API docs for rate‑limit headers.

Limitations & Caveats

• Runs cannot be edited once archived; you must duplicate the run to start a new cycle.
• Deleting a Test Suite cascades deletions to all its runs—back up data before removal.
• API bulk creation is subject to rate limits; use page_size and offset parameters to paginate.
• Automated results import requires the test case to exist in the suite; otherwise the API returns a 400 error.

Practical Verification Checklist

1. Login to QTest and confirm the new run is listed.
2. Execute one test case and verify status updates in the UI.
3. Generate a PDF report and cross‑check counts.
4. Run the API /api/v2/runs endpoint and confirm the run appears.
5. Delete the run, then restore it from the Archive to confirm recovery.

Conclusion

With this workflow you can reliably create, manage, and automate Test Runs in QTest, ensuring that testing data is accurate, traceable, and ready for stakeholder consumption.