Test Cases

The test cases endpoints allow you to retrieve information about test cases in your project. This can be useful for planning test runs and monitoring your test coverage.

Types of Test Cases

In QA Sphere, there are three types of test cases:

Standalone Test Case: These are the standard test cases.
Template Test Case: Similar to standalone test cases, but they can include parameters within ${} in their title, preconditions, and steps. These parameters can be replaced with specific values to generate multiple test cases from the same template.
Filled Test Cases: Automatically created by the system by substituting parameter values in template test cases. They inherit all properties from the parent template test case.

important

Users can directly create standalone and template test cases. When creating template test cases, users can specify a list of values for the parameters, which the system uses to automatically generate the corresponding filled test cases.
Updates to a template test case will also update the corresponding filled test cases.
Deletion is permitted for all three types of test cases. Deleting a template test case will also delete the associated filled test cases. Deleting a filled test case will only remove that specific test case.
Test runs include only standalone and filled test cases.

List Project Test Cases

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

Retrieves all test cases within a project based on the filters provided in the request query parameters.

Path Parameters

project_id: The project identifier (can be either the project code or UUID)

Query Parameters

All query parameters are optional and some can be specified multiple times using the format param=value1&param=value2&param=value3.

Parameter	Type	Multiple	Description	Allowed Values	Example
`page`	number	no	Page number for fetching test cases in batches		`page=1`
`limit`	number	no	Maximum number of test cases to return, or maximum test cases per page (default: 10, if `page` is specified)		`limit=10`
`sortField`	string	no	Field to sort by	`id`, `seq`, `folder_id`, `author_id`, `pos`, `title`, `priority`, `created_at`, `updated_at`, `legacy_id`	`sortField=title`
`sortOrder`	string	no	Sort order (requires `sortField`; default: `desc`)	`asc`, `desc`	`sortOrder=desc`
`types`	string	yes	Filter test cases by type	`standalone`, `template`, `filled`	`types=standalone`
`search`	string	no	Filter test cases by title (case insensitive, partial matches)		`search=ui`
`folders`	number	yes	Filter test cases by folder ID (does not consider child folders)		`folders=10&folders=12`
`tags`	number	yes	Filter test cases by tag ID		`tags=12`
`priorities`	string	yes	Filter test cases by priority	`high`, `medium`, `low`	`priorities=low`
`draft`	bool	no	Filter test cases by draft status	`true`, `false`	`draft=true`
`templateTCaseIds`	string	yes	Filter test cases by their parent template test case identifiers		`templateTCaseIds=1CEPaUhuR_yNsLvcbYJhw46`
`cf_${custom field system name}`	string	yes	Filter test cases by custom field value	The values for custom fields are defined under Settings > Custom Fields	`cf_automation=Automated`
`include`	string	yes	Include additional fields in the response which are omitted by default	`steps`, `tags`, `project`, `folder`, `path`, `customFields`, `parameterValues`	`include=steps`

tip

Use pagination when project contains large number of test cases
Only include necessary non-default fields
Different filters are combined with AND logic
Multiple values for the same filter are combined with OR logic

Example Request

Fetch all test cases with default fields

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

Fetch all test cases with "Automation" custom field to be "Automated"

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

Fetch all test cases with "Known Issue" custom field to be "Yes"

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

Fetch 20 test cases sorted by title in ascending order

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?limit=20&sortField=title&sortOrder=asc

Fetch 7th page of test cases sorted by pos where each page contains 15 test cases

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?page=7&limit=15&sortField=pos&sortOrder=asc

Fetch all draft test cases

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

Fetch 10 most recent added test cases

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?limit=10&sortField=created_at&sortOrder=desc

Fetch test cases with "backend" in their title

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

Fetch test cases with "backend" in their title and include custom fields

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

Fetch all filled test cases corresponding to template test case ID '1CEPaUhuR_yNsLvcbYJhw46'

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

Response Fields

{
  total: number,                  // Total number of filtered test cases
  page: number,                   // Current page number (if page is specified in the request)
  limit: number,                  // Limit (if specified) or number of test cases per page (if page is specified in the request)
  data: Array<{                   // List of test case objects
    id: string                    //   Unique identifier of the test case
    legacyId: string              //   Legacy identifier of the test case. Empty string if the test case has no legacy ID
    version: number               //   Version of the test case. Updates to test (except folder/pos) creates a new version
    type: string                  //   Type of the test case (`standalone` | `template` | `filled`)
    title: string                 //   Title of the test case
    seq: number                   //   Sequence number of the test case. Test cases in a project are assigned incremental sequence numbers
    folderId: number              //   Identifier of the folder where the test case is placed
    pos: number                   //   Ordered position (0 based) of the test case in its folder
    priority: string              //   Priority of the test case (`high` | `medium` | `low`)
    comment: string               //   Test description/precondition
    files: Array<{                //   List of files attached to the test case
      id: string                  //     Unique identifier of the file
      fileName: string            //     Name of the file
      mimeType: string            //     Mime type of the file
      size: number                //     Size of the file
      url: string                 //     URL of the file
    }>
    links: Array<{                //   Additional links relevant to the test case
      text: string                //     Title of the link
      url: string                 //     URL of the link
    }>
    authorId: number              //   Unique identifier of the user who added the test case
    isDraft: boolean              //   Whether the test case is still in draft state
    isLatestVersion: boolean      //   Whether this is the latest version of the test case
    createdAt: string             //   Test case creation time (ISO 8601 format)
    updatedAt: string             //   Test case updation time (ISO 8601 format)

    // Non default fields
    customFields: {               //   Custom fields defined for the test case
      [key: string]: string       //     Key-value pairs of custom field names and values
    }
    tags: Array<{                 //   List of test case tags
      id: number                  //     Unique identifier of the tag
      title: string               //     Title of the tag
    }>
    steps: Array<{                //   List of test case steps
      description: string         //     Details of steps
      expected:    string         //     Expected result from the step
    }>
    parameterValues: {            //   The details of corresponding filled tcases (relevant only for template tcases)
      tcaseId: string             //     ID of the filled tcase
      tcaseVersion: int           //     Version of the filled tcase
      values: {                   //     Values corresponding to the parameters in the template tcase for this filled tcase
        [key: string]: string
      }
    }
    folder: {                     //   Details of the folder where the test case is placed
      id: number                  //     Unique identifier for the folder
      title: string               //     Name of the folder
      comment: string             //     Additional notes or description
      pos: number                 //     Position of the folder among its siblings
      parentId: number            //     ID of the parent folder (0 for root folders)
      projectId: string           //     ID of the project the folder belongs to
    },
    path: Array<{                 //   Path to the folder where the test cases is placed
      id: number                  //     Unique identifier for the folder
      title: string               //     Name of the folder
      comment: string             //     Additional notes or description
      pos: number                 //     Position of the folder among its siblings
      parentId: number            //     ID of the parent folder (0 for root folders)
      projectId: string           //     ID of the project the folder belongs to
    }>
    project: {                    //   Details of project to which the test case belong
      id: string                  //     Unique identifier of the project
      code: string                //     Short code of the project
      title: string               //     Title of the project
      overviewTitle: string       //     Title of the project overview
      overviewDescription: string //     Project Overview
      links: {                    //     Links relevant to the project
        text: string              //       Title of the link
        url: string               //       URL of the link
      }
      archivedAt: string          //     Project archival time (ISO 8601 format)
      createdAt: string           //     Project creation time (ISO 8601 format)
      updatedAt: string           //     Project updation time (ISO 8601 format)
    }
  }>
}

Example Response

{
  "total": 2,
  "page": 0,
  "limit": 0,
  "data": [
    {
      "id": "1CJg36j1c_yFYPRcmZaoqp3",
      "version": 6,
      "legacyId": "",
      "seq": 55,
      "type": "standalone",
      "folderId": 26,
      "pos": 0,
      "title": "User should see the content according to the \"About Us\" information",
      "priority": "high",
      "comment": "<p>The \"About Us\" page is opened</p>",
      "authorId": 1,
      "files": [
        {
          "id": "89f7a73e-043c-4fe1-beb3-9e8d8df55f28",
          "fileName": "Screencast from 24-03-25 14:27:33.webm",
          "mimeType": "video/webm",
          "size": 555431
        }
      ],
      "links": [],
      "isDraft": false,
      "isLatestVersion": true,
      "createdAt": "2025-03-25T10:48:14.243475+02:00",
      "updatedAt": "2025-03-25T10:48:14.243475+02:00"
    },
    {
      "id": "1CJg36j28_EaAHxNiNQNNTn",
      "version": 6,
      "legacyId": "",
      "seq": 56,
      "type": "standalone",
      "folderId": 26,
      "pos": 1,
      "title": "User should place the order successfully after entering valid data in all required fields and selecting the \"Card Payment\" payment",
      "priority": "high",
      "comment": "<ol><li><p>The \"Checkout\" page is opened</p></li><li><p>There are pizzas, drinks and desserts</p></li></ol>",
      "authorId": 1,
      "files": [
        {
          "id": "bf5fcc05-44a2-46b2-87fb-2501cfedb1f7",
          "fileName": "Screenshot 2025-01-15 18:54:44.png",
          "mimeType": "image/png",
          "size": 89567
        }
      ],
      "links": [],
      "isDraft": false,
      "isLatestVersion": true,
      "createdAt": "2025-03-25T10:48:34.66935+02:00",
      "updatedAt": "2025-03-25T10:48:34.66935+02:00"
    }
  ]
}

Get Test Case

GET/api/public/v0/project/{project_id}/tcase/{tcase_or_legacy_id}

Get details of a single test case using its ID, sequence or legacy ID.

Path Parameters

project_id: The project identifier (can be either the project code or UUID)
tcase_or_legacy_id: The test case identifier (can be one of test case UUID, sequence or legacy ID)

Example Request

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

Response Fields

{
  id: string                    // Unique identifier of the test case
  legacyId: string              // Legacy identifier of the test case. Empty string if the test case has no legacy ID
  version: number               // Version of the test case. Updates to test (except folder/pos) creates a new version
  type: string                  // Type of the test case (`standalone` | `template` | `filled`)
  title: string                 // Title of the test case
  seq: number                   // Sequence number of the test case. Test cases in a project are assigned incremental sequence numbers
  folderId: number              // Identifier of the folder where the test case is placed
  pos: number                   // Ordered position (0 based) of the test case in its folder
  priority: string              // Priority of the test case (`high` | `medium` | `low`)
  comment: string               // Test description/precondition
  steps: Array<{                // List of test case steps
    description: string         //   Details of steps
    expected:    string         //   Expected result from the step
  }>
  tags: Array<{                 // List of test case tags
    id: number                  //   Unique identifier of the tag
    title: string               //   Title of the tag
  }>
  files: Array<{                // List of files attached to the test case
    id: string                  //   Unique identifier of the file
    fileName: string            //   Name of the file
    mimeType: string            //   Mime type of the file
    size: number                //   Size of the file
    url?: string                //   URL of the file (optional, not present in sample)
  }>
  requirements: Array<{         // Test case requirement (currently only single requirement is supported on UI)
    id: string                  //   Unique identifier of the requirement
    text: string                //   Title of the requirement
    url: string                 //   URL of the requirement
  }>
  links: Array<{                // Additional links relevant to the test case
    text: string                //   Title of the link
    url: string                 //   URL of the link
  }>
  customFields: {               // Custom fields defined for the test case
    [key: string]: string       //   Key-value pairs of custom field names and values
  }
  parameterValues: {            // The details of corresponding filled tcases (relevant only for template tcases)
    tcaseId: string             //   ID of the filled tcase
    tcaseVersion: int           //   Version of the filled tcase
    values: {                   //   Values corresponding to the parameters in the template tcase for this filled tcase
      [key: string]: string
    }
  }
  authorId: number              // Unique identifier of the user who added the test case
  isDraft: boolean              // Whether the test case is still in draft state
  isLatestVersion: boolean      // Whether this is the latest version of the test case
  createdAt: string             // Test case creation time (ISO 8601 format)
  updatedAt: string             // Test case updation time (ISO 8601 format)
}

Sample Response

{
  "id": "1CJg36j1c_yFYPRcmZaoqp3",
  "version": 6,
  "legacyId": "",
  "seq": 55,
  "type": "standalone",
  "folderId": 26,
  "pos": 0,
  "title": "User should see the content according to the \"About Us\" information",
  "priority": "high",
  "comment": "<p>The \"About Us\" page is opened</p>",
  "authorId": 1,
  "files": [
    {
      "id": "89f7a73e-043c-4fe1-beb3-9e8d8df55f28",
      "fileName": "Screencast from 24-03-25 14:27:33.webm",
      "mimeType": "video/webm",
      "size": 555431
    }
  ],
  "links": [],
  "requirements": [
    {
      "text": "AUTO-REQ-2 Automated Tests Requirements",
      "url": "https://github.com/Hypersequent/bistro-e2e/docs/automated-testing/requirements#auto-req-2",
      "id": "1CJg36j1s_WwGRdtSYt43VZ"
    }
  ],
  "tags": [
    { "id": 1, "title": "About Us" },
    { "id": 206, "title": "automation" },
    { "id": 3, "title": "REQ-4" }
  ],
  "steps": [
    {
      "description": "<p>Automated validation of About Us content</p>",
      "expected": "<p>Content matches expected About Us information</p>"
    }
  ],
  "customFields": { "automation": "Automated", "known_issue": "No" },
  "isDraft": false,
  "isLatestVersion": true,
  "createdAt": "2025-03-25T10:48:14.243475+02:00",
  "updatedAt": "2025-03-25T10:48:14.243475+02:00"
}

Get Test Case Count

GET/api/public/v0/project/{project_id}/tcase/count

Returns the total number of test cases that match the specified filters. If no filters are provided, returns the total count of all test cases in the project.

Path Parameters

project_id: The project identifier (can be either the project code or UUID)

Query Parameters

Parameter	Type	Description	Example
`folders`	number	Filter by folder IDs	`folders=1&folders=2`
`recursive`	boolean	Include test cases in subfolders (requires `folders`)	`recursive=true`
`tags`	number	Filter by tag IDs	`tags=1&tags=2`
`priorities`	string	Filter by priority levels (high, medium, low)	`priorities=high&priorities=medium`
`draft`	boolean	Filter by draft status	`draft=true`

Example Requests

Basic Count

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

Filter Examples

Folder-based counting:

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/count?folders=1&recursive=true"

Priority-based counting:

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/count?priorities=high"

Tag-based counting:

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

Draft status counting:

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/count?draft=true"

Custom field counting:

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/count?cf_automation=Automated"

Response Format

{
  count: number // Total number of test cases matching the filters
}

Example Response

{
  "count": 4
}

Error Responses

Status Code	Description
401	Invalid or missing API key
403	Insufficient permissions or suspended tenant
404	Project not found
400	Invalid filter parameters
500	Internal server error

Use Cases

Monitor test coverage by counting test cases across different folders
Track high-priority test case volume
Review draft test case count before publishing
Plan test runs based on tagged test cases

Filter Behavior

If no filters are specified, all test cases in the project are counted
Different filters are combined with AND logic
Multiple values for the same filter are combined with OR logic
The recursive parameter only applies when folders is specified

Update Test Case

PATCH/api/public/v0/project/{project_id}/tcase/{tcase_or_legacy_id}

Updates a test case using its ID, sequence or legacy ID. Only users with role User or higher are allowed to update test cases.

Path Parameters

project_id: The project identifier (can be either the project code or UUID)
tcase_or_legacy_id: The test case identifier (can be one of test case UUID, sequence or legacy ID)

Request Body

All fields are optional; only those fields that need to be updated should be included in the request. For a filled test case, only priority can be updated.

{
  title?: string            // Optional: Test case title (must be between 1-255 characters)
  priority?: string         // Optional: Test case priority (`high` | `medium` | `low`)
  comment?: string          // Optional: Test case description/precondition
  isDraft?: boolean         // Optional: To publish a draft test case. A published test case cannot be converted to draft
  steps?: Array<{           // Optional: List of test case steps
    description: string     //   Details of steps
    expected:    string     //   Expected result from the step
  }>
  tags?: string[]           // Optional: List of test case tags (title)
  requirements?: Array<{    // Optional: Test case requirement (currently only single requirement is supported on UI)
    text: string            //   Title of the requirement (must be between 1-255 characters)
    url: string             //   URL of the requirement (must be between 1-255 characters)
  }>
  links?: Array<{           // Optional: Additional links relevant to the test case
    text: string            //   Title of the link (must be between 1-255 characters)
    url: string             //   URL of the link (must be between 1-255 characters)
  }>
  customFields?: Array<{    // Optional: Custom field values to update. Only specified custom fields are updated, others are left as is
    [key: string]: string   //   Only custom fields applied and enabled for a project should be specified
  }>
  parameterValues?: Array<{ // Optional: Values to substitute for parameters in the filled test cases (only relevant for template types)
    tcaseId: string         //   Should be specified in order to update existing filled test case. Otherwise a new filled test case would be created. If an existing filled test case is absent in the update request, it is deleted
    values: {               //   Values for the parameters in the template test case to be substituted for this filled test case
      [key: string]: string
    }
  }>
}

Example Request

Updating Test Case Title, Priority And Custom Field Value

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Changing to corresponding cursor after hovering the element",
    "priority": "high",
    "customFields": {
      "automation": "Automated"
    }
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/1

Updating Multiple Custom Fields Values

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "customFields": {
      "automation": "Cannot be Automated",
      "known_issue": "Yes"
    }
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/56

note

Custom fields must be created through the web UI before you can set their values via API
Use the system name (lowercase with underscores) of the custom field, not its display name
The field value must match one of the predefined options for the custom field
When updating custom fields, only the fields you specify will be modified
To remove a custom field value, you need to set it to an empty string (if allowed by the field configuration)

Example Response

Status: 200 OK

{
  "message": "Test case updated"
}

Error Responses

Status Code	Description
400	Converting a published test case to draft
401	Invalid or missing API key
403	Insufficient permissions or suspended tenant
404	Project or test case not found
500	Internal server error while updating test case

Test Cases

Types of Test Cases​

List Project Test Cases​

Path Parameters​

Query Parameters​

Example Request​

Fetch all test cases with default fields​

Fetch all test cases with "Automation" custom field to be "Automated"​

Fetch all test cases with "Known Issue" custom field to be "Yes"​

Fetch 20 test cases sorted by title in ascending order​

Fetch 7th page of test cases sorted by pos where each page contains 15 test cases​

Fetch all draft test cases​

Fetch 10 most recent added test cases​

Fetch test cases with "backend" in their title​

Fetch test cases with "backend" in their title and include custom fields​

Fetch all filled test cases corresponding to template test case ID '1CEPaUhuR_yNsLvcbYJhw46'​

Response Fields​

Example Response​

Get Test Case​

Path Parameters​

Example Request​

Response Fields​

Sample Response​

Get Test Case Count​

Path Parameters​

Query Parameters​

Example Requests​

Basic Count​

Filter Examples​

Response Format​

Example Response​

Error Responses​

Update Test Case​

Path Parameters​

Request Body​

Example Request​

Updating Test Case Title, Priority And Custom Field Value​

Updating Multiple Custom Fields Values​

Example Response​

Error Responses​

Types of Test Cases

List Project Test Cases

Path Parameters

Query Parameters

Example Request

Fetch all test cases with default fields

Fetch all test cases with "Automation" custom field to be "Automated"

Fetch all test cases with "Known Issue" custom field to be "Yes"

Fetch 20 test cases sorted by title in ascending order

Fetch 7th page of test cases sorted by pos where each page contains 15 test cases

Fetch all draft test cases

Fetch 10 most recent added test cases

Fetch test cases with "backend" in their title

Fetch test cases with "backend" in their title and include custom fields

Fetch all filled test cases corresponding to template test case ID '1CEPaUhuR_yNsLvcbYJhw46'

Response Fields

Example Response

Get Test Case

Path Parameters

Example Request

Response Fields

Sample Response

Get Test Case Count

Path Parameters

Query Parameters

Example Requests

Basic Count

Filter Examples

Response Format

Example Response

Error Responses

Update Test Case

Path Parameters

Request Body

Example Request

Updating Test Case Title, Priority And Custom Field Value

Updating Multiple Custom Fields Values

Example Response

Error Responses