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.

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`
`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`	`priority=low`
`draft`	bool	no	Filter test cases by draft status	`true`, `false`	`draft=true`
`include`	string	yes	Include additional fields in the response which are omitted by default	`steps`, `tags`, `project`, `folder`, `path`	`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 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

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
    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
    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
    }>
    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": 56,
  "page": 0,
  "limit": 1,
  "data": [
    {
      "id": "1CEPaUhuR_yNsLvcbYJhw46",
      "legacyId": "",
      "version": 1,
      "title": "User should see the image, name, description and price of the drink",
      "seq": 46,
      "folderId": 17,
      "pos": 2,
      "priority": "high",
      "comment": "<ol><li><p>The \"Today's Menu\" block is opened</p></li><li><p>The \"Drinks\" tab is opened</p></li></ol>",
      "files": [
        {
          "id": "135b56f5-d2f7-4e35-aaaa-65a45c7ffe1a",
          "fileName": "bistro-drinks-menu-screenshot.png",
          "mimeType": "image/png",
          "size": 222410,
          "url": "https://your-company.your-region-code.qasphere.com/example/bistro-delivery/images/bistro-drinks-menu-screenshot.png"
        }
      ],
      "links": null,
      "authorId": 1,
      "isDraft": false,
      "isLatestVersion": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "tags": [
        {
          "id": 148,
          "title": "Products"
        },
        {
          "id": 126,
          "title": "REQ-3"
        }
      ],
      "steps": [
        {
          "description": "<p>Look at the drinks list</p>",
          "expected": "<p>User should see:</p><ol><li><p>Valid image of the drink</p></li><li><p>Valid name of the drink</p></li><li><p>Valid description of the drink</p></li><li><p>Valid price of the drink</p></li></ol>"
        }
      ],
      "folder": {
        "id": 17,
        "parentId": 11,
        "title": "Drinks",
        "comment": "",
        "projectId": "1CEPaUhUd_whirk5zJ7kY5i",
        "pos": 1
      }
    }
  ]
}

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
  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
  }>
  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
  }>
  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": "1CEPaUhuR_yNsLvcbYJhw46",
  "legacyId": "",
  "version": 1,
  "title": "User should see the image, name, description and price of the drink",
  "seq": 46,
  "folderId": 17,
  "pos": 2,
  "priority": "high",
  "comment": "<ol><li><p>The \"Today's Menu\" block is opened</p></li><li><p>The \"Drinks\" tab is opened</p></li></ol>",
  "steps": [
    {
      "description": "<p>Look at the drinks list</p>",
      "expected": "<p>User should see:</p><ol><li><p>Valid image of the drink</p></li><li><p>Valid name of the drink</p></li><li><p>Valid description of the drink</p></li><li><p>Valid price of the drink</p></li></ol>"
    }
  ],
  "tags": [
    {
      "id": 148,
      "title": "Products"
    },
    {
      "id": 126,
      "title": "REQ-3"
    }
  ],
  "files": [
    {
      "id": "135b56f5-d2f7-4e35-aaaa-65a45c7ffe1a",
      "fileName": "bistro-drinks-menu-screenshot.png",
      "mimeType": "image/png",
      "size": 222410,
      "url": "https://your-company.your-region-code.qasphere.com/example/bistro-delivery/images/bistro-drinks-menu-screenshot.png"
    }
  ],
  "requirements": null,
  "links": null,
  "authorId": 1,
  "isDraft": false,
  "isLatestVersion": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

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"

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.

{
  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)
  }>
}

Example Request

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"
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/1

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

List Project Test Cases​

Path Parameters​

Query Parameters​

Example Request​

Fetch all test cases with default fields​

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​

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​

Example Response​

Error Responses​

List Project Test Cases

Path Parameters

Query Parameters

Example Request

Fetch all test cases with default fields

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

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

Example Response

Error Responses