QA Sphere

https://qasphere.com/docs
Admin
QA Sphere is a test management system designed to help teams plan, organize, execute, track software...
Tokens:214,961
Snippets:1,659
Trust Score:8.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get project example response

Source: https://qasphere.com/docs/api/projects

Example JSON response for a successful Get Project request, showing a project with code 'BD' and its details.

```json
{
  "id": "1CJo8oDjj_vkGo2rQAdzz4F",
  "code": "BD",
  "title": "Bistro Delivery",
  "description": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
  "overviewTitle": "Bistro Delivery - Example",
  "overviewDescription": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
  "links": [
    {
      "text": "Bistro Delivery Site",
      "url": "https://hypersequent.github.io/bistro/"
    },
    {
      "text": "Automation Tests",
      "url": "https://github.com/Hypersequent/bistro-e2e"
    },
    {
      "text": "QA Sphere CLI Tool",
      "url": "https://github.com/Hypersequent/qas-cli"
    }
  ],
  "createdAt": "2025-01-02T11:41:19.547371+04:00",
  "updatedAt": "2025-01-02T11:41:19.547371+04:00",
  "archivedAt": null
}
```

--------------------------------

### List Projects Example Request

Source: https://qasphere.com/docs/api/projects

Example request to list all projects. Requires an API key in the Authorization header.

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

--------------------------------

### Create Project Example Response (201)

Source: https://qasphere.com/docs/api/projects

Example response with status 201 Created, returning the newly created project's `id`.

```json
{
  "id": "1CJo8oDjj_vkGo2rQAdzz4F"
}
```

--------------------------------

### Get Current User Example Response (JSON)

Source: https://qasphere.com/docs/api/users

Example JSON response from the Get Current User endpoint. Shows a user object with id, email, name, avatar, and role.

```json
{
  "user": {
    "id": 42,
    "email": "you@example.com",
    "name": "Your Name",
    "avatar": null,
    "role": "admin"
  }
}
```

--------------------------------

### List Projects Example Response

Source: https://qasphere.com/docs/api/projects

Example response for the list projects endpoint. Shows a project with links, timestamps, and null archivedAt.

```json
{
  "projects": [
    {
      "id": "1CJo8oDjj_vkGo2rQAdzz4F",
      "code": "BD",
      "title": "Bistro Delivery",
      "description": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
      "overviewTitle": "Bistro Delivery - Example",
      "overviewDescription": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
      "links": [
        {
          "text": "Bistro Delivery Site",
          "url": "https://hypersequent.github.io/bistro/"
        },
        {
          "text": "Automation Tests",
          "url": "https://github.com/Hypersequent/bistro-e2e"
        },
        {
          "text": "QA Sphere CLI Tool",
          "url": "https://github.com/Hypersequent/qas-cli"
        }
      ],
      "createdAt": "2025-01-02T11:41:19.547371+04:00",
      "updatedAt": "2025-01-02T11:41:19.547371+04:00",
      "archivedAt": null
    }
  ]
}
```

--------------------------------

### Example Request - Live Run With All Test Cases

Source: https://qasphere.com/docs/api/run

A cURL request example for creating a live run that includes all test cases by providing empty filter arrays.

```bash
curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Complete Test Suite",
    "description": "<p>Run with all test cases from the project</p>",
    "type": "live",
    "milestoneId": 5,
    "queryPlans": [{
      "folderIds": [],
      "tagIds": [],
      "priorities": []
    }]
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run
```

--------------------------------

### Example Request - Live Run With Filtered Test Cases

Source: https://qasphere.com/docs/api/run

A cURL request example for creating a live run using multiple query plans with folder, tag, and priority filters.

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

--------------------------------

### Install qas-cli globally with npm

Source: https://qasphere.com/docs/cli

Installs the qas-cli package globally via npm. Requires Node.js 22.0.0 or higher.

```bash
npm install -g qas-cli
```

--------------------------------

### List Users Example Response (JSON)

Source: https://qasphere.com/docs/api/users

Example JSON response from the List Users endpoint. Shows two users with different roles and authorization types.

```json
{
  "users": [
    {
      "email": "admin@example.com",
      "name": "System Admin",
      "role": "admin",
      "authorizationTypes": ["password"],
      "totpEnabled": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "lastActivity": "2024-11-14"
    },
    {
      "email": "tester@example.com",
      "name": "Test Engineer",
      "role": "test-runner",
      "authorizationTypes": ["password", "google"],
      "totpEnabled": false,
      "createdAt": "2024-03-15T00:00:00Z",
      "lastActivity": "2024-11-14"
    }
  ]
}
```

--------------------------------

### Link Test Case to Requirements Example

Source: https://qasphere.com/docs/reports/traceability-report

Shows how to link a test case to requirements during creation. The example lists a test case name and the requirement IDs it covers.

```text
Test Case: "User can reset password"
Linked Requirements: REQ-042, REQ-043
```

--------------------------------

### List Users Example Request (curl)

Source: https://qasphere.com/docs/api/users

Example curl request to list all users. Requires an API key with Admin role permissions. The endpoint is restricted to administrators only.

```bash
curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/users
```

--------------------------------

### Example Response for Created Test Case

Source: https://qasphere.com/docs/api/tcases

Example response with status 201 Created. Shows the id and seq fields returned after successfully creating a test case.

```json
{
  "id": "1CJg36j1c_yFYPRcmZaoqp3",
  "seq": 57
}
```

--------------------------------

### Get Current User Example Request (API Key)

Source: https://qasphere.com/docs/api/users

Example curl request to get the current user using an API key. Available to any authenticated role.

```bash
curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/users/me
```

--------------------------------

### qasphere junit-upload usage examples

Source: https://qasphere.com/docs/integrations/ci-cd/gitlab

Usage examples for the qasphere junit-upload command, covering default run creation, uploading to an existing run, static names, environment variable placeholders, date/time placeholders, attachments, multiple files, and force upload. The --run-name option is ignored when -r is specified.

```bash
# Create new run with default name template
qasphere junit-upload ./junit-results/results.xml

# Upload to existing run (--run-name is ignored)
qasphere junit-upload -r https://company.eu1.qasphere.com/project/BD/run/42 ./junit-results/results.xml

# Simple static name
qasphere junit-upload --run-name "v1.4.4-rc5" ./junit-results/results.xml

# With environment variables
qasphere junit-upload --run-name "Pipeline #{env:CI_PIPELINE_ID} - {env:CI_COMMIT_REF_NAME}" ./junit-results/results.xml
# Output: "Pipeline #12345 - main"

# With date placeholders
qasphere junit-upload --run-name "Release {YYYY}-{MM}-{DD}" ./junit-results/results.xml
# Output: "Release 2025-01-15"

# With date and time placeholders
qasphere junit-upload --run-name "Nightly Tests {MMM} {DD}, {YYYY} at {HH}:{mm}" ./junit-results/results.xml
# Output: "Nightly Tests Jan 15, 2025 at 22:34"

# Complex template with multiple placeholders
qasphere junit-upload --run-name "Build {env:BUILD_NUMBER} - {YYYY}/{MM}/{DD} {hh}:{mm} {AMPM}" ./junit-results/results.xml
# Output: "Build v1.4.4-rc5 - 2025/01/15 10:34 PM"

# With attachments
qasphere junit-upload --attachments ./junit-results/results.xml

# Multiple files
qasphere junit-upload ./junit-results/*.xml

# Force upload on errors
qasphere junit-upload --force ./junit-results/results.xml
```

--------------------------------

### Get Current User Example Request (OAuth Bearer)

Source: https://qasphere.com/docs/api/users

Example curl request to get the current user using an OAuth Bearer token. Available to any authenticated role.

```bash
curl \
  -H "Authorization: Bearer your-oauth-access-token" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/users/me
```

--------------------------------

### Run-name examples with date, branch, and commit placeholders

Source: https://qasphere.com/docs/integrations/ci-cd/github-actions

Three examples of --run-name with different placeholder combinations: date/time, branch and commit SHA, and complete metadata with formatted date. Each uses the qasphere junit-upload command with the specified run name and results file.

```yaml
# Workflow with date and time
- run: qasphere junit-upload --run-name "Run #{env:GITHUB_RUN_NUMBER} - {YYYY}-{MM}-{DD} {HH}:{mm}" ./junit-results/results.xml

# Branch and commit info
- run: qasphere junit-upload --run-name "{env:GITHUB_REF_NAME} - {env:GITHUB_SHA}" ./junit-results/results.xml

# Complete metadata
- run: qasphere junit-upload --run-name "Build #{env:GITHUB_RUN_NUMBER} ({env:GITHUB_REF_NAME}) - {MMM} {DD}, {hh}:{mm} {AMPM}" ./junit-results/results.xml
```

--------------------------------

### Get Statuses Example Response (JSON)

Source: https://qasphere.com/docs/api/settings

Example JSON response from the GET statuses endpoint, showing the list of statuses with their properties. Includes default statuses (open, passed, failed, skipped, blocked) and custom statuses (custom1-custom4).

```json
{
  "statuses": [
    {
      "id": "open",
      "name": "Open",
      "color": "blue",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "passed",
      "name": "Passed",
      "color": "green",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "failed",
      "name": "Failed",
      "color": "red",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "skipped",
      "name": "Skipped",
      "color": "gray",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "blocked",
      "name": "Blocked",
      "color": "orange",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "custom1",
      "name": "Known Issue",
      "color": "teal",
      "isDefault": false,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "custom2",
      "name": "Retest",
      "color": "orange",
      "isDefault": false,
      "isActive": false,
      "inUse": false
    },
    {
      "id": "custom3",
      "name": "Custom 3",
      "color": "purple",
      "isDefault": false,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "custom4",
      "name": "Custom 4",
      "color": "teal",
      "isDefault": false,
      "isActive": false,
      "inUse": false
    }
  ]
}
```

--------------------------------

### Pre-create a run, then upload automation results into it

Source: https://qasphere.com/docs/cli/public-api

Creates a run and then uploads JUnit results into it. Assumes QAS_TOKEN and QAS_URL are configured and uses jq for JSON parsing.

```bash
RUN_ID=$(qasphere api runs create --project-code PRJ \
  --title "CI build $BUILD_NUMBER" --type static \
  --query-plans '[{"tcaseIds": ["abc123"]}]' \
  --milestone-id 7 | jq -r '.id')

qasphere junit-upload -r "$QAS_URL/project/PRJ/run/$RUN_ID" ./test-results.xml
```

--------------------------------

### Get Statuses Example Request (curl)

Source: https://qasphere.com/docs/api/settings

Example curl command to retrieve the current status configuration from the QA Sphere settings endpoint. Requires an API key in the Authorization header.

```bash
curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/settings/preferences/status
```

--------------------------------

### GET /api/public/v0/project/BD/run/1/tcase

Source: https://qasphere.com/docs/api/authentication

Example of making an authenticated request to the QA Sphere API using the Bearer authentication scheme.

```APIDOC
## [GET] /api/public/v0/project/BD/run/1/tcase

### Description
Example of making an authenticated request to the QA Sphere API using the Bearer authentication scheme.

### Method
GET

### Endpoint
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/tcase

### Parameters
#### Headers
- **Authorization** (string) - Required - API key in the format `Bearer your.api.key.here`

### Request Example
```bash
curl \
  -H "Authorization: Bearer your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/tcase
```

### Response
#### Success Response (200)
No response body details provided.

#### Error Responses
- **401** - Missing Authorization, Invalid API Key Format, or Invalid Credentials
- **403** - Suspended Tenant or User, Network Access Denied, or Restricted Endpoint
```

--------------------------------

### Get Shared Precondition Request

Source: https://qasphere.com/docs/api/shared_preconditions

Example cURL request to retrieve a shared precondition by project ID and precondition ID.

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

--------------------------------

### Example Request

Source: https://qasphere.com/docs/api/run

A cURL command to create a log entry for a test run using an API key.

```bash
curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "<p>Build #1234 failed: 3 test cases did not pass</p>"
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/log
```

--------------------------------

### Get project with curl

Source: https://qasphere.com/docs/api/projects

Example curl command to fetch a project by its code 'BD'. Requires an API key in the Authorization header.

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

--------------------------------

### Create Project Example Request (curl)

Source: https://qasphere.com/docs/api/projects

Example curl command to create a project. Requires an API key in the Authorization header and sends a JSON body with project details. The endpoint is `POST /api/public/v0/project`.

```bash
curl -X POST \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BD",
    "title": "Bistro Delivery",
    "links": [
      {"url": "https://hypersequent.github.io/bistro/", "text": "Bistro Delivery Site"},
      {"url": "https://github.com/Hypersequent/bistro-e2e", "text": "Automation Tests"}
    ],
    "overviewTitle": "Bistro Delivery - Example",
    "overviewDescription": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process.</p>"
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project
```

--------------------------------

### GET /api/public/v0/project/BD/run/1/tcase (Legacy)

Source: https://qasphere.com/docs/api/authentication

Example of making an authenticated request to the QA Sphere API using the legacy ApiKey authentication scheme.

```APIDOC
## [GET] /api/public/v0/project/BD/run/1/tcase (Legacy)

### Description
Example of making an authenticated request to the QA Sphere API using the legacy ApiKey authentication scheme.

### Method
GET

### Endpoint
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/tcase

### Parameters
#### Headers
- **Authorization** (string) - Required - API key in the format `ApiKey your.api.key.here`

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

### Response
#### Success Response (200)
No response body details provided.

#### Error Responses
- **401** - Missing Authorization, Invalid API Key Format, or Invalid Credentials
- **403** - Suspended Tenant or User, Network Access Denied, or Restricted Endpoint
```

--------------------------------

### Get Run Test Case Request

Source: https://qasphere.com/docs/api/run

Example cURL request to retrieve a run test case using an API key for authentication.

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

--------------------------------

### Run Query Plan with Multiple Tags

Source: https://qasphere.com/docs/api/tag

Example showing how to include multiple tag IDs in a query plan to select test cases matching any of the provided tags.

```json
{
  "tagIds": [2, 3] // Selects test cases with either "api-tests" or "smoke-tests" tags
}
```

--------------------------------

### junit-upload usage examples

Source: https://qasphere.com/docs/integrations/ci-cd/bitbucket

Usage examples for the junit-upload command, covering default naming, existing runs, static names, environment variables, date/time placeholders, attachments, multiple files, and force upload. The --run-name option is ignored when -r is used.

```bash
# Create new run with default name template
qasphere junit-upload ./junit-results/results.xml

# Upload to existing run (--run-name is ignored)
qasphere junit-upload -r https://company.eu1.qasphere.com/project/BD/run/42 ./junit-results/results.xml

# Simple static name
qasphere junit-upload --run-name "v1.4.4-rc5" ./junit-results/results.xml

# With environment variables
qasphere junit-upload --run-name "Build #{env:BITBUCKET_BUILD_NUMBER} - {env:BITBUCKET_BRANCH}" ./junit-results/results.xml
# Output: "Build #12345 - main"

# With date placeholders
qasphere junit-upload --run-name "Release {YYYY}-{MM}-{DD}" ./junit-results/results.xml
# Output: "Release 2025-01-15"

# With date and time placeholders
qasphere junit-upload --run-name "Nightly Tests {MMM} {DD}, {YYYY} at {HH}:{mm}" ./junit-results/results.xml
# Output: "Nightly Tests Jan 15, 2025 at 22:34"

# Complex template with multiple placeholders
qasphere junit-upload --run-name "Build {env:BUILD_NUMBER} - {YYYY}/{MM}/{DD} {hh}:{mm} {AMPM}" ./junit-results/results.xml
# Output: "Build v1.4.4-rc5 - 2025/01/15 10:34 PM"

# With attachments
qasphere junit-upload --attachments ./junit-results/results.xml

# Multiple files
qasphere junit-upload ./junit-results/*.xml

# Force upload on errors
qasphere junit-upload --force ./junit-results/results.xml
```

--------------------------------

### Mark Cypress tests with QA Sphere markers

Source: https://qasphere.com/docs/cli-usage-cypress

Example Cypress test file using Mocha-style test names with the PROJECT-SEQUENCE marker (e.g., BD-023) at the start of each test name.

```typescript
// cypress/e2e/cart.cy.ts
describe('Cart', () => {
  it('BD-023: User should see product list on the Checkout page', () => {
    cy.visit('/');
    cy.get('.menu-item').first().find('.add-to-cart').click();
    cy.get('.checkout-btn').click();
    cy.get('.checkout-items').should('be.visible');
  });

  it('BD-022: User should place order with valid data', () => {
    // ...
  });
});
```

--------------------------------

### Force Upload on Errors with --force

Source: https://qasphere.com/docs/integrations/ci-cd/bitbucket

Use the --force option to continue uploading even if some tests can't be matched. This example shows a complete Bitbucket pipeline step that installs the CLI and runs the upload with --force.

```yaml
- step:
    name: Upload to QA Sphere
    script:
      - npm install -g qas-cli
      - qasphere junit-upload --force ./junit-results/results.xml
```

--------------------------------

### Test Locally First with Environment Variables

Source: https://qasphere.com/docs/integrations/ci-cd/bitbucket

Test the integration locally before pushing to Bitbucket. Set QAS_TOKEN and QAS_URL environment variables, run tests, then upload results with npx qas-cli.

```bash
# Set environment variables
export QAS_TOKEN=your.api.key
export QAS_URL=https://company.eu1.qasphere.com

# Run tests
npm test

# Upload results
npx qas-cli junit-upload ./junit-results/results.xml
```

--------------------------------

### Example JSON response

Source: https://qasphere.com/docs/api/tcases

Example JSON response showing a count of 4 test cases.

```json
{
  "count": 4
}
```
Tokens:
Raw