Test Runs

The runs endpoints allow you to create and manage test executions in your project. You can create new runs, list existing runs, manage test cases within runs, and track their results.

Types of Runs

QA Sphere supports three types of test runs:

1. User Selection (Static Structure)

• Specified by type: "static_struct"
• Test cases can be selected by their IDs or using filters (folders, tags, priorities)
• Test cases in the run are fixed after creation unless manually updated
• Updates to test case properties (e.g. title, steps) are reflected for open statuses

2. Static Runs

• Specified by type: "static"
• Test cases can be selected directly by IDs or using filters (folders, tags, priorities)
• Similar to Static Structure in that test cases are fixed after creation
• Updates to test case properties (e.g. title, steps) are not reflected in the run, even for open statuses

3. Live Runs

• Specified by type: "live"
• Only dynamic selection based on folder, tag, and priority filters
• Test cases are automatically added/removed when they match or do not match filter criteria
• Supports multiple query plans for flexible test case selection

Test Case Selection

For static and static_struct runs, you can select test cases in multiple ways:

1. Direct selection using tcaseIds
2. Using filters (same as live runs):
   • folderIds: Select test cases from specific folders
   • tagIds: Select test cases with specific tags
   • priorities: Select test cases with specific priority levels
   • Any combination of these filters

When using filters, the system automatically resolves them to a fixed set of test cases at creation time.

note

Folder and position changes of test cases are always propagated to all run types, even for closed runs or test cases with results. Test case versions are fixed on non-open status, updates to test case properties (e.g. title, steps) are not reflected in the run.

List Project Runs

GET/api/public/v0/project/{project_id}/run

Returns all runs in a project with their current status.

Query Parameters

Parameter	Description	Example
closed	Filter by run status	closed=true or closed=false
milestoneIds	Filter by milestone	milestoneIds=1&milestoneIds=2
limit	Maximum number of runs to return	limit=10

Example Request

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run

Response Fields

{
 runs: Array<{
   id: number              // Unique identifier of the test run
   type: string           // Type of the run 'static' | 'static_struct' | 'live'
   projectId: string      // ID of the project this run belongs to
   project: {             // Project details
     id: string          // Project unique identifier
     code: string        // Project code
     title: string       // Project title
   }
   milestoneId: number | null  // ID of associated milestone if any
   milestone: object | null    // Milestone details if associated
   assignmentId: number       // ID of the assigned user
   assignment: {              // Assignment details
     id: number             // User ID
     email: string         // User email
     name: string          // User display name
     avatar: string        // URL to user's avatar
     role: string         // User role in the project
   }
   title: string           // Title of the test run
   description: string     // Description of the test run
   statusCounts: {         // Count of test cases by status
     all: number          // Total test cases
     blocked: number      // Blocked test cases
     failed: number       // Failed test cases
     open: number         // Open test cases
     passed: number       // Passed test cases
     skipped: number      // Skipped test cases
   }
   timeSpent: number | null     // Time spent on the run
   createdAt: string           // Creation timestamp
   closedAt: string | null     // Closure timestamp
   closedByUserId: number | null // ID of user who closed the run
 }>
}

Create New Run

POST/api/public/v0/project/{project_id}/run

Creates a new test run in the project.

Request Body

{
  title: string                  // Required: Run title
  description?: string           // Optional: Run description
  type: "static" | "static_struct" | "live"  // Required: Run type
  milestoneId?: number          // Optional: Associated milestone
  assignmentId?: number         // Optional: Assigned user
  queryPlans: Array<{            // Required: Test case selection criteria
    // Common filters for all run types:
    folderIds?: Array<number>    // Select test cases from folders
    tagIds?: Array<number>       // Select test cases with tags
    priorities?: Array<"low" | "medium" | "high">  // Select by priority

    // Additional for static/static_struct runs:
    tcaseIds?: Array<string>     // Directly specify test cases
  }>
}

Field Constraints

• title: Must be 1-255 characters long and unique within the project
• description: Maximum 512 characters
• queryPlans:
  • For non-live runs: Only one query plan allowed
  • For live runs: At least one folderID required per query plan
• assignmentId: Must be an active user with permissions above Viewer role

Example Request - Live Run With Filtered TCases

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sprint 23 Regression",
    "description": "Regression test suite for Sprint 23 release",
    "type": "live",
    "milestoneId": 5,
    "queryPlans": [{
      "folderIds": [1, 2],
      "tagIds": [1],
      "priorities": ["high"]
    }]
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run

Example Request - Static Run With Specific Test Cases

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Specific Test Cases Run",
    "type": "static",
    "queryPlans": [{
      "tcaseIds": ["1CEPaUhgH_Tvt2LZygwVRQa", "1CAPaUhgH_Tvt2LZygwVRTb", "1EEPaUhgH_Tvt2LZygwVRLm"]
    }]
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run

Response

Status: 201 Created

{
  "id": 2
}

Clone Existing Run

POST/api/public/v0/project/{project_id}/run/clone

Creates a new run by cloning an existing one. For live runs, the new run will reflect current test case states.

Request Body

{
  runId: number                // Required: Source run ID to clone
  title: string                // Required: New run title
  description?: string         // Optional: New description
  milestoneId?: number        // Optional: New milestone
  assignmentId?: number       // Optional: New assignee
}

Field Constraints

• title: Must be 1-255 characters long and unique within the project
• description: Maximum 512 characters
• runId: Must be a valid run ID in the project
• milestoneId: Must be a valid milestone ID if provided
• assignmentId: Must be an active user with permissions above Viewer role

Example Request

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "runId": 1,
    "title": "Sprint 24 Regression - Clone",
    "description": "Cloned regression suite for Sprint 24",
    "milestoneId": 5,
    "assignmentId": 1
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/clone

Example Response

{
  "id": 2
}

note

When cloning a live run, the new run will:

• Maintain the same query plans as the original run
• Reflect the current state of test cases (may differ from the original run)
• Start with all test cases in 'open' status regardless of the original run's results

List Run Test Cases

GET/api/public/v0/project/{project_id}/run/{run_id}/tcase

Returns all test cases in a run with their current status.

Query Parameters

Parameter	Description
include=folder	Include folder information for each test case

Example Request

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/tcase?include=folder

Response Fields

{
 "tcases": Array<{
   id: string           // Unique identifier of the test case
   version: number      // Version number of the test case
   legacyId: string    // Legacy identifier (if any)
   folderId: number    // ID of the folder containing the test case
   pos: number         // Position within the folder
   seq: number         // Sequence number
   title: string       // Title/description of the test case
   priority: string    // Priority level (high, medium, etc.)
   status: string      // Current status of the test case
   isAutomated: boolean // Whether the test case is automated
 }>
}

Sample Response

{
  "tcases": [
    {
      "id": "1CGeNaNVt_Axa7TcMjUm6Zh",
      "version": 1,
      "legacyId": "",
      "folderId": 11848,
      "pos": 3,
      "seq": 8,
      "title": "The \"Checkout\" page with products from the cart should be shown after clicking the \"Checkout\" button",
      "priority": "high",
      "status": "open",
      "isAutomated": false
    },
    {
      "id": "1CGeNaNWP_Eiq5mjzPsKSX9",
      "version": 1,
      "legacyId": "",
      "folderId": 11848,
      "pos": 4,
      "seq": 9,
      "title": "The cart is still filled after going back from the \"Checkout\" page without submitting it",
      "priority": "medium",
      "status": "open",
      "isAutomated": false
    }
  ]
}

Best Practices

• Use live runs for ongoing test suites that should automatically update
• Use static runs for fixed test sets like release certifications
• Always provide descriptive titles and link runs to milestones when applicable
• Assign runs to specific users for better accountability