`)
* `src` - Media source URL (http/https URLs only)
* `width` - Element width
### Tables (``, ` `)
* `colspan` - Column span
* `rowspan` - Row span
### Tables (``, `
This test case requires careful attention to the
user interface elements.
```
### Lists and Structure
```html
Test prerequisites:
User must be logged in
Account must have admin privileges
Database must be in test mode
```
### Links and References
```html
For more information, see the
API documentation .
```
### Tables
```html
Test Results Summary
Passed 25
Failed 3
```
### Removed Content
```html
paragraph with click handler
normal div
paragraph with class
paragraph with click handler
normal div
paragraph with class
```
**Malformed HTML Behavior**
When HTML content is malformed (such as missing opening/closing tags or unmatched quotes), the sanitization process may produce unexpected results:
* **Missing closing tags**: Content may be restructured or truncated
* **Unmatched quotes**: Attributes may be removed entirely
* **Invalid nesting**: Elements may be reordered or removed
* **Unknown elements**: Completely stripped from output
Always validate your HTML structure before sending it to the API to ensure predictable results.
---
# Agent Skill
URL: /docs/cli/agent-skill
The qas-cli repository ships a [SKILL.md](https://github.com/Hypersequent/qas-cli/blob/main/skills/qas-cli/SKILL.md) — a condensed reference written for AI coding agents (Claude Code, Cursor, and any other agent that supports the [skills](https://github.com/vercel-labs/skills) format). Once the skill is registered, the agent can drive QA Sphere on your behalf — listing projects, authoring test cases, opening and closing runs, posting results, and pulling reports — without you scripting any of it.
## Install the skill
```bash
npx skills add Hypersequent/qas-cli
```
The command writes the skill into your agent's local skill registry. Re-run it to update the skill in place.
Each agent has its own way of activating registered skills. See the [Vercel skills registry](https://github.com/vercel-labs/skills) for the current per-agent install instructions and supported runtimes.
## Prerequisites
* qas-cli installed (`npm install -g qas-cli` or available via `npx qas-cli`). See [Overview](https://qasphere.com/docs/cli).
* Authenticated session (`qasphere auth login`) or `QAS_TOKEN` + `QAS_URL` configured. See [Auth](https://qasphere.com/docs/cli/auth).
The skill reads the same `qasphere -h` output a human would, so it stays current with the installed CLI — there's nothing for you to keep in sync.
## What the agent can do
With the skill loaded, you can describe the outcome you want in natural language and the agent composes the right `qasphere api ...` calls. The CLI prints JSON; the agent renders it however the conversation needs — Markdown tables, matplotlib/Plotly charts, SVG, HTML, CSV exports.
A few examples that work out of the box:
* *"Plot the pass rate of the last 20 closed runs in project PRJ as a line chart."* → the agent calls `qasphere api runs list --project-code PRJ --closed true`, computes `passed / all` per run from `statusCounts`, renders a chart.
* *"Which folders in PRJ have the most failing tests this week?"* → combines `runs list`, `runs test-cases list`, and `folders list` to aggregate failures by folder.
* *"Generate a Markdown summary of run 42 with the pass/fail breakdown and a list of failing test case titles."* → calls `runs test-cases list --project-code PRJ --run-id 42` and formats the output.
* *"Create a folder structure for the Authentication area with Login, OAuth, and MFA subfolders, then scaffold five test cases under Login."* → calls `folders bulk-create` followed by `test-cases create`.
You don't need to pre-script anything — describe the report or change you want, and let the agent compose the API calls.
## Further reading
* Source: [`skills/qas-cli/SKILL.md`](https://github.com/Hypersequent/qas-cli/blob/main/skills/qas-cli/SKILL.md) in the qas-cli repository — the canonical reference the agent reads.
* Skill format: [vercel-labs/skills](https://github.com/vercel-labs/skills).
* Underlying commands: [Public API](https://qasphere.com/docs/cli/public-api) and [Result Upload](https://qasphere.com/docs/integrations/result-upload).
---
# Auth
URL: /docs/cli/auth
The CLI needs to know which QA Sphere instance to talk to and how to authenticate. Two methods are supported: interactive OAuth login (recommended) and an API token in environment or config files.
## OAuth login (recommended)
```bash
qasphere auth login
```
This prompts for your team name, opens a browser for authorization, and stores OAuth tokens persistently. The flow requires an interactive terminal (TTY) — it isn't suitable for headless CI.
OAuth sessions are valid for 90 days, with the window resetting on every CLI use. As long as you keep running `qasphere` commands, you won't need to re-authenticate. Tokens are refreshed automatically when within 5 minutes of expiry.
Other auth commands:
```bash
qasphere auth status # Show currently active credential and verify the server is reachable
qasphere auth logout # Clear stored credentials
```
### Where credentials are stored
OAuth tokens are written to the operating system keyring (under the `qasphere-cli` service) when one is available. If the keyring is unavailable, the CLI falls back to `~/.config/qasphere/credentials.json` with file mode `0600`.
## API token
For CI/CD pipelines and any non-interactive environment, configure an API token instead. Set:
* `QAS_TOKEN` — your QA Sphere API token (see the [API Authentication](/docs/api/authentication) guide for how to generate one)
* `QAS_URL` — base URL of your QA Sphere instance, e.g. `https://qas.eu1.qasphere.com`
These variables can be defined as environment variables, in a `.env` file, or in a `.qaspherecli` file in the current directory or any parent.
```sh
# .qaspherecli (or .env)
QAS_TOKEN=your_token
QAS_URL=https://qas.eu1.qasphere.com
```
Never commit `.env` or `.qaspherecli` files containing real tokens. Use your CI provider's secret store (GitHub Actions Secrets, GitLab CI/CD Variables, Bitbucket Repository Variables) instead.
## Credential resolution order
When the CLI needs credentials, it resolves them in the following order (first match wins):
1. `QAS_TOKEN` and `QAS_URL` environment variables
2. `.env` file in the current working directory
3. System keyring (set by `qasphere auth login`)
4. `~/.config/qasphere/credentials.json` (fallback when keyring is unavailable)
5. `.qaspherecli` file in the current directory or any parent directory
If no source resolves, the CLI prints a setup guide to stderr and exits with status `1`.
## Generating an API token
API tokens are created in the QA Sphere web UI:
1. Click the gear icon ` commands to inspect or change QA Sphere state. Every command prints JSON to stdout for easy piping into tools like `jq`. See [Public API](https://qasphere.com/docs/cli/public-api).
* **Scripts and CI/CD automation** — orchestrate projects, folders, test cases, milestones, runs, and results from shell scripts and pipelines. See [CI/CD Integrations](https://qasphere.com/docs/integrations/ci-cd).
* **Test result uploads** — push JUnit XML, Playwright JSON, and Allure result directories at the end of an automated run. See [Result Upload](https://qasphere.com/docs/integrations/result-upload).
* **AI coding agents** — a bundled skill lets Claude Code, Cursor, and similar agents drive QA Sphere through the CLI in natural language. See [Agent Skill](https://qasphere.com/docs/cli/agent-skill).
qas-cli is open source:
[github.com/Hypersequent/qas-cli](https://github.com/Hypersequent/qas-cli).
Track development, report issues, and contribute on GitHub.
## Installation
### Requirements
Node.js 22.0.0 or higher. No other runtime is needed — the CLI works alongside Python, Go, Java, or any other test stack.
If you don't already have Node.js, install it via your system package manager:
* macOS: `brew install node`
* Ubuntu/Debian: `sudo apt install nodejs npm`
* Windows / other: download from [nodejs.org](https://nodejs.org/)
### Via npm (global)
```bash
npm install -g qas-cli
```
Verify:
```bash
qasphere --version
```
Update later with:
```bash
npm update -g qas-cli
```
### Via npx
```bash
npx qas-cli
```
On first use you'll be prompted to download the package. `npx qas-cli` works in every context the `qasphere` command does.
Verify:
```bash
npx qas-cli --version
```
npx caches packages. To force the latest version, run `npx clear-npx-cache`
(or pin a specific version, e.g. `npx qas-cli@0.5.0`).
## Shell completion
The CLI ships with tab completion for commands and options. Append the completion script to your shell profile:
**Zsh:**
```bash
qasphere completion >> ~/.zshrc
```
**Bash:**
```bash
qasphere completion >> ~/.bashrc
```
Restart your shell (or `source` the profile) and pressing `Tab` will autocomplete commands and flags.
## Rate limits
The QA Sphere API allows **20 requests per second per user**, shared across all of that user's
API keys and OAuth authorizations. Exceeding it returns `429 Too Many Requests`. See
[API Rate Limiting](/docs/api/api_intro#rate-limiting) for the full set of limits.
The CLI handles this for you. On a `429` it waits and retries automatically, honoring the
`Retry-After` header the API sends and otherwise backing off exponentially — up to 5 retries
over roughly 30 seconds. Result uploads are also deliberately paced: attachments upload at most
3 batches at a time, and results are posted in sequential batches rather than all at once. A
normal upload, even one with thousands of results, stays well under the limit.
Automatic retry on `429` was added in **v0.8.0**. On v0.7.0 and earlier the CLI fails
immediately when rate limited, which typically shows up as a failed upload step in CI. Check
your version with `qasphere --version` and upgrade with `npm update -g qas-cli`.
If you still hit rate limits on a current version, the usual cause is several CI jobs running
concurrently under the same QA Sphere user. Because the limit is per user rather than per API
key, adding more API keys will not help — give the parallel jobs separate user accounts instead.
## Where to next
* [Auth](https://qasphere.com/docs/cli/auth) — log in via OAuth or configure an API key.
* [Public API](https://qasphere.com/docs/cli/public-api) — call the full QA Sphere REST API from the terminal.
* [Result Upload](https://qasphere.com/docs/integrations/result-upload) — upload JUnit XML, Playwright JSON, or Allure results into a run. Framework guides and CI/CD examples live in the [Integrations](https://qasphere.com/docs/integrations-intro) section.
* [Agent Skill](https://qasphere.com/docs/cli/agent-skill) — register the CLI with Claude Code, Cursor, and other coding agents.
* [CI/CD Integrations](https://qasphere.com/docs/integrations/ci-cd) — wire the CLI into GitHub Actions, GitLab CI/CD, or Bitbucket Pipelines.
---
# Public API
URL: /docs/cli/public-api
The `qasphere api` command exposes the full QA Sphere public API as terminal commands. Every command prints JSON to stdout (errors to stderr) for clean piping into `jq`, scripts, and CI pipelines.
```bash
qasphere api [options]
```
Exit code is `0` on success, `1` on failure. Pass `-h` to any subcommand for its full signature, options, examples, and a link to the matching REST endpoint reference.
## Command tree
```
qasphere api
├── audit-logs
│ └── list # List audit log entries
├── custom-fields
│ └── list --project-code # List custom fields
├── files
│ └── upload --file # Upload a file attachment
├── folders
│ ├── list --project-code # List folders
│ └── bulk-create --project-code --folders # Create/update folders
├── milestones
│ ├── list --project-code # List milestones
│ └── create --project-code --title # Create milestone
├── projects
│ ├── list # List all projects
│ ├── get --project-code # Get project by code
│ └── create --code --title # Create project
├── requirements
│ └── list --project-code # List requirements
├── results
│ ├── create --project-code --run-id --tcase-id --status # Create result
│ └── batch-create --project-code --run-id --items # Batch create results
├── runs
│ ├── create --project-code --title --type --query-plans # Create run
│ ├── list --project-code # List runs
│ ├── clone --project-code --run-id --title # Clone run
│ ├── close --project-code --run-id # Close run
│ ├── test-cases
│ │ ├── list --project-code --run-id # List test cases in run
│ │ └── get --project-code --run-id --tcase-id # Get test case in run
│ └── logs
│ └── create --project-code --run-id --comment # Create run log
├── settings
│ ├── list-statuses # List result statuses
│ └── update-statuses --statuses # Update custom statuses
├── shared-preconditions
│ ├── list --project-code # List shared preconditions
│ └── get --project-code --id # Get shared precondition
├── shared-steps
│ ├── list --project-code # List shared steps
│ └── get --project-code --id # Get shared step
├── tags
│ └── list --project-code # List tags
├── test-cases
│ ├── list --project-code # List test cases
│ ├── get --project-code --tcase-id # Get test case
│ ├── count --project-code # Count test cases
│ ├── create --project-code --body # Create test case
│ └── update --project-code --tcase-id --body # Update test case
├── test-plans
│ └── create --project-code --body # Create test plan
└── users
└── list # List all users
```
`qasphere api files upload --file ...` uses the public batch upload endpoint internally and returns the first uploaded file from that response.
For per-endpoint request/response details, see the [REST API Endpoints reference](/docs/api/api_intro).
## Pagination
List commands support pagination via:
* `--page ` and `--limit ` — offset-based pagination
* `--sort-field ` and `--sort-order ` — sorting (where supported)
`audit-logs list` uses cursor-based pagination instead:
* `--after ` — continuation cursor from the previous page
* `--count ` — page size
## Passing JSON bodies
Commands that mutate complex resources (`runs create`, `test-cases create`/`update`, `test-plans create`, `results create`/`batch-create`, `folders bulk-create`, `settings update-statuses`) accept their payload three ways:
* `--body ''` — inline JSON string
* `--body-file ` — path to a JSON file
* Individual field flags — e.g. `--title`, `--status`, `--comment`
Field flags merge into `--body` / `--body-file` with field flags taking precedence. The combined body must always be valid JSON.
## Workflow examples
The examples below assume `QAS_TOKEN` and `QAS_URL` are configured (see [Auth](https://qasphere.com/docs/cli/auth)) and use [`jq`](https://stedolan.github.io/jq/) for JSON parsing.
### 1. Open a run, post results, and close it
Useful when results come from a tool that doesn't produce JUnit/Playwright/Allure output:
```bash
RUN_ID=$(qasphere api runs create --project-code PRJ \
--title "Smoke $(date +%Y-%m-%d)" --type static \
--query-plans '[{"tcaseIds": ["abc123", "def456"]}]' | jq -r '.id')
qasphere api results batch-create --project-code PRJ --run-id "$RUN_ID" \
--items '[{"tcaseId": "abc123", "status": "passed"}, {"tcaseId": "def456", "status": "failed", "comment": "timeout on /cart"}]'
qasphere api runs close --project-code PRJ --run-id "$RUN_ID"
```
### 2. Run-progress report
List open runs with their pass/fail/open counts:
```bash
qasphere api runs list --project-code PRJ --closed false \
| jq '.[] | {title, passed: .statusCounts.passed, failed: .statusCounts.failed, open: .statusCounts.open, total: .statusCounts.all}'
```
### 3. Pre-create a run, then upload automation results into it
```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
```
### 4. Bulk-create folders and test cases
```bash
qasphere api folders bulk-create \
--project-code PRJ \
--folders '[{"path": ["Authentication", "Login"]}, {"path": ["Authentication", "OAuth"]}]'
qasphere api test-cases create \
--project-code PRJ \
--body '{"title": "Login with valid credentials", "type": "standalone", "folderId": 1, "priority": "high"}'
```
## Error handling
* **Missing credentials** — the CLI prints a setup guide to stderr and exits with code `1`. See [Auth](https://qasphere.com/docs/cli/auth).
* **Validation errors** — invalid CLI arguments or API validation failures are reported to stderr with the offending option name.
* **HTTP errors** — formatted and printed to stderr. Use `--verbose` for full stack traces.
---
# Export
URL: /docs/export
QA Sphere allows exporting test case library in CSV (Comma-Separated Values) format. To do that:
1. Open a project and go to **Test Cases** tab
2. Click events all
```
Replace `` with your QA Sphere project code (for example, `BD`). The bot joins the channel automatically and confirms the subscription.
events ` | Subscribe the channel to project notifications |
| `/qasphere unsubscribe project events ` | Unsubscribe from some or all of a project's notifications |
| `/qasphere list` | List the active subscriptions in this channel |
| `/qasphere link` | Link your Slack account to QA Sphere |
| `/qasphere` | Show help |
### Event Categories
Subscriptions are configured per event category:
| Category | Covers |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `runs` | Test runs created, updated, closed, reopened, or deleted; test plans created, closed, reopened, or deleted; milestones closed or deleted |
| `results` | Test results recorded, updated, or deleted (batch operations are summarized in a single message) |
| `all` | Both of the above |
## Notifications
Once subscribed, the QA Sphere bot posts a message to the channel whenever a matching event occurs. Each notification links back to the entity in QA Sphere and includes key details such as the project code, state, and the user who performed the action.
> // Each array represents the full folder path hierarchy in the request as an array of folder IDs, from root to leaf
}
```
**Details:**
* The `ids` field is an array where each item corresponds to one input folder path.
* Each inner array contains folder IDs that map 1:1 to the specified folder path in the request.
* For example, if your path is `["Frontend", "Components", "Navigation"]`, the result could be `[12, 13, 14]` where `12` is "Frontend", `13` is "Components", `14` is "Navigation".
* Newly created folders will always get new IDs; existing folders return their original IDs.
* The order of returned arrays matches the order of the input `folders` in the request.
### Example Request
```bash
curl -X POST \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"folders": [
{
"path": ["Frontend", "Components", "Navigation"],
"comment": "Tests for navigation components
"
},
{
"path": ["Frontend", "Components", "Forms"],
"comment": "Form validation and interaction tests
"
},
{
"path": ["Backend", "API", "Authentication"],
"comment": "Authentication endpoint tests
"
}
]
}' \
https://company.qasphere.com/api/public/v0/project/BD/tcase/folder/bulk
```
### Example Response
Status: 200 OK
```json
{
"ids": [
[12, 13, 14],
[12, 13, 15],
[16, 17, 18]
]
}
```
### Behavior
* **Creates nested structure**: Automatically creates all parent folders in the path if they don't exist
* **Updates existing folders**: If a folder path already exists, only the comment is updated
* **Idempotent**: Running the same request multiple times produces the same result
* **Preserves hierarchy**: Maintains proper parent-child relationships between folders
* **Position assignment**: New folders are positioned automatically within their parent
### Example Folder Creation
Given the request above, the following folder structure would be created:
```
Frontend/
├── Components/
│ ├── Navigation/ (comment: "Tests for navigation components")
│ └── Forms/ (comment: "Form validation and interaction tests")
Backend/
└── API/
└── Authentication/ (comment: "Authentication endpoint tests")
```
### Error Responses
| Status Code | Description |
| ----------- | -------------------------------------------- |
| 400 | Invalid request body or folder path format |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 404 | Project not found |
| 500 | Internal server error |
### Validation Rules
* Each folder name in the path must be 1-255 characters long
* Folder names cannot be empty strings
* The `path` array cannot be empty
* folder comment should be in html format
This endpoint is particularly useful for:
* Setting up folder structures during project initialization
* Bulk importing test case organization from external systems
* Synchronizing folder structures across projects
* Automating test case creation
The endpoint only updates the `comment` field for existing folders. Other properties like position and parent relationships are preserved.
---
# Milestones
URL: /docs/api/milestone
The milestones endpoint allows you to retrieve all milestones associated with a project. Milestones help organize and track test runs across different versions or phases of your project.
## List Project Milestones
`GET /api/public/v0/project/{project_id}/milestone`
Returns a list of all milestones in the project. This endpoint is particularly useful when you need milestone IDs for creating or cloning test runs.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Query Parameters
| Parameter | Type | Description | Example |
| ---------- | ---- | ------------------------------------------- | --------------- |
| `archived` | bool | Fetch only archived/non-archived milestones | `archived=true` |
### Response
Status: 200 OK
```typescript
{
milestones: Array<{
// Array of milestone objects
id: number // Unique identifier for the milestone
title: string // Name of the milestone
createdAt: string // Creation timestamp in ISO 8601 format
updatedAt: string // Last update timestamp in ISO 8601 format
archivedAt: string | null // Timestamp when the milestone was archived in ISO 8601 format
}>
}
```
### Example Request
#### Fetch all milestones
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/milestone
```
#### Fetch only non-archived milestones
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/milestone?archived=false
```
### Example Response
```json
{
"milestones": [
{
"id": 1,
"title": "Version 0.9",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z",
"archivedAt": null
},
{
"id": 2,
"title": "Version 1.0",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z",
"archivedAt": "2024-02-01T00:00:00.000Z"
}
]
}
```
### Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------- |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 404 | Project not found |
| 500 | Internal server error during milestone listing |
## Create Milestone
`POST /api/public/v0/project/{project_id}/milestone`
Creates a new milestone in the project. Milestones help organize test runs by version or project phase.
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Request Body
```typescript
{
title: string // Required: Name of the milestone (max 255 chars)
}
```
### Response
Status: 201 Created
```typescript
{
id: number // The ID of the newly created milestone
}
```
### Example Request
#### Using cURL
```bash
curl \
-X POST \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"title": "Version 2.0"
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/milestone
```
#### Request Body (JSON)
```json
{
"title": "Version 2.0"
}
```
#### Minimal Request Example
```json
{
"title": "Quick Fix Release"
}
```
### Example Response
```json
{
"id": 42
}
```
### Validation Rules
* **Title**: Required, must be unique within the project, maximum 255 characters
### Error Responses
| Status Code | Description |
| ----------- | ----------------------------------------------- |
| 400 | Invalid request body or validation error |
| 401 | Invalid or missing API key |
| 403 | Duplicate milestone title exists in the project |
| 404 | Project not found |
| 500 | Internal server error during milestone creation |
After creating a milestone, you can use its ID when creating test runs to associate them with this specific project version or phase.
---
# Test Plans
URL: /docs/api/plan
The plans endpoints allow you to create and manage test plans in your project. A test plan is a collection of test runs that are organized and executed together, typically for a specific milestone or release. Write operations (create/update/delete) can only be performed by users with role test runner or with higher privileges.
## Test Plan Overview
A test plan consists of:
* **Title and Description**: Basic information about the plan
* **Milestone**: Optional association with a project milestone
* **Runs**: One or more test runs, each containing a set of test cases
Each run within a plan:
* Has its own title
* Can be assigned to a specific user
* Can be associated with a configuration
* Contains exactly one query plan that specifies the test cases to include
## Create New Test Plan
`POST /api/public/v0/project/{project_id}/plan`
Creates a new test plan in the project with one or more test runs.
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Request Body
```typescript
{
title: string // Required: Plan title (max 255 characters)
description?: html // Optional: Plan description
milestoneId?: number // Optional: Associated milestone
runs: Array<{ // Required: List of runs in the plan
title: string // Required: Run title (max 255 characters)
assignmentId?: number // Optional: Assigned user ID
configurationId?: string // Optional: Configuration ID
queryPlans: Array<{ // Required: Exactly one query plan per run
tcaseIds: Array // Required: Test case IDs to include
}>
}>
}
```
**Field Constraints**
* `title`: Must be 1-255 characters long and unique within the milestone (or among plans without milestones)
* `description`: HTML content that will be sanitized
* `milestoneId`: The milestone must belong to the project and must not be archived
* `runs`: Must contain at least one run
* Each run must have exactly one query plan
* `tcaseIds`: Must be valid test case IDs belonging to the project
* `assignmentId`: Must be an active user with permissions above Viewer role
* Test case IDs must be standalone or filled types (not templates)
### Response
Status: 201 Created
```json
{
"id": 5
}
```
The response contains the ID of the newly created test plan.
### Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------------- |
| 400 | Invalid request data or validation errors |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions (requires Test Runner role) |
| 404 | Project not found |
| 409 | Conflict - Plan title already exists in milestone |
| 500 | Internal server error |
## Common Use Cases
### Cross-Browser Testing
Create a test plan to run the same test suite across different browsers:
```json
{
"title": "Release 3.0 Browser Compatibility",
"description": "Browser compatibility testing for Release 3.0
",
"milestoneId": 15,
"runs": [
{
"title": "Chrome Tests",
"configurationId": "chrome_latest",
"assignmentId": 3,
"queryPlans": [
{
"tcaseIds": [
"1CEPaUhgH_Tvt2LZygwVRQa",
"1CAPaUhgH_Tvt2LZygwVRTb",
"1DAPaUhgH_Tvt2LZygwVRSc",
"1EEPaUhgH_Tvt2LZygwVRLm",
"1FEPaUhgH_Tvt2LZygwVRNn"
]
}
]
},
{
"title": "Firefox Tests",
"configurationId": "firefox_latest",
"assignmentId": 3,
"queryPlans": [
{
"tcaseIds": [
"1CEPaUhgH_Tvt2LZygwVRQa",
"1CAPaUhgH_Tvt2LZygwVRTb",
"1DAPaUhgH_Tvt2LZygwVRSc",
"1EEPaUhgH_Tvt2LZygwVRLm",
"1FEPaUhgH_Tvt2LZygwVRNn"
]
}
]
},
{
"title": "Safari Tests",
"configurationId": "safari_latest",
"assignmentId": 3,
"queryPlans": [
{
"tcaseIds": [
"1CEPaUhgH_Tvt2LZygwVRQa",
"1CAPaUhgH_Tvt2LZygwVRTb",
"1DAPaUhgH_Tvt2LZygwVRSc",
"1EEPaUhgH_Tvt2LZygwVRLm",
"1FEPaUhgH_Tvt2LZygwVRNn"
]
}
]
},
{
"title": "Edge Tests",
"configurationId": "edge_latest",
"assignmentId": 3,
"queryPlans": [
{
"tcaseIds": [
"1CEPaUhgH_Tvt2LZygwVRQa",
"1CAPaUhgH_Tvt2LZygwVRTb",
"1DAPaUhgH_Tvt2LZygwVRSc",
"1EEPaUhgH_Tvt2LZygwVRLm",
"1FEPaUhgH_Tvt2LZygwVRNn"
]
}
]
}
]
}
```
### Multi-Platform Testing
Test the same application across different platforms and devices:
```json
{
"title": "Mobile App Platform Testing",
"description": "Testing mobile app across different platforms
",
"runs": [
{
"title": "iOS 17 - iPhone 15",
"configurationId": "ios17_iphone15",
"assignmentId": 4,
"queryPlans": [
{
"tcaseIds": [
"1GEPaUhgH_Tvt2LZygwVROo",
"1HEPaUhgH_Tvt2LZygwVRPp",
"1IEPaUhgH_Tvt2LZygwVRQq",
"1JEPaUhgH_Tvt2LZygwVRRr",
"1KEPaUhgH_Tvt2LZygwVRSs"
]
}
]
},
{
"title": "iOS 17 - iPad Pro",
"configurationId": "ios17_ipad_pro",
"assignmentId": 4,
"queryPlans": [
{
"tcaseIds": [
"1GEPaUhgH_Tvt2LZygwVROo",
"1HEPaUhgH_Tvt2LZygwVRPp",
"1IEPaUhgH_Tvt2LZygwVRQq",
"1JEPaUhgH_Tvt2LZygwVRRr",
"1KEPaUhgH_Tvt2LZygwVRSs"
]
}
]
},
{
"title": "Android 14 - Pixel 8",
"configurationId": "android14_pixel8",
"assignmentId": 5,
"queryPlans": [
{
"tcaseIds": [
"1GEPaUhgH_Tvt2LZygwVROo",
"1HEPaUhgH_Tvt2LZygwVRPp",
"1IEPaUhgH_Tvt2LZygwVRQq",
"1JEPaUhgH_Tvt2LZygwVRRr",
"1KEPaUhgH_Tvt2LZygwVRSs"
]
}
]
},
{
"title": "Android 14 - Samsung Galaxy",
"configurationId": "android14_galaxy",
"assignmentId": 5,
"queryPlans": [
{
"tcaseIds": [
"1GEPaUhgH_Tvt2LZygwVROo",
"1HEPaUhgH_Tvt2LZygwVRPp",
"1IEPaUhgH_Tvt2LZygwVRQq",
"1JEPaUhgH_Tvt2LZygwVRRr",
"1KEPaUhgH_Tvt2LZygwVRSs"
]
}
]
}
]
}
```
### Regression Testing Across Environments
Run regression tests across different deployment environments:
```json
{
"title": "Regression Test Suite - All Environments",
"description": "Full regression testing across staging and production-like environments
",
"runs": [
{
"title": "Regression Tests - Staging US",
"configurationId": "staging_us_east",
"assignmentId": 3,
"queryPlans": [
{
"tcaseIds": [
"1LEPaUhgH_Tvt2LZygwVRTt",
"1MEPaUhgH_Tvt2LZygwVRUu",
"1NEPaUhgH_Tvt2LZygwVRVv",
"1OEPaUhgH_Tvt2LZygwVRWw",
"1PEPaUhgH_Tvt2LZygwVRXx",
"1QEPaUhgH_Tvt2LZygwVRYy"
]
}
]
},
{
"title": "Regression Tests - Staging EU",
"configurationId": "staging_eu_west",
"assignmentId": 4,
"queryPlans": [
{
"tcaseIds": [
"1LEPaUhgH_Tvt2LZygwVRTt",
"1MEPaUhgH_Tvt2LZygwVRUu",
"1NEPaUhgH_Tvt2LZygwVRVv",
"1OEPaUhgH_Tvt2LZygwVRWw",
"1PEPaUhgH_Tvt2LZygwVRXx",
"1QEPaUhgH_Tvt2LZygwVRYy"
]
}
]
},
{
"title": "Regression Tests - Staging APAC",
"configurationId": "staging_apac",
"assignmentId": 5,
"queryPlans": [
{
"tcaseIds": [
"1LEPaUhgH_Tvt2LZygwVRTt",
"1MEPaUhgH_Tvt2LZygwVRUu",
"1NEPaUhgH_Tvt2LZygwVRVv",
"1OEPaUhgH_Tvt2LZygwVRWw",
"1PEPaUhgH_Tvt2LZygwVRXx",
"1QEPaUhgH_Tvt2LZygwVRYy"
]
}
]
}
]
}
```
### Component-Based Testing
Create test plans with different test cases for distinct components or modules:
```json
{
"title": "Sprint 23 Feature Test Plan",
"description": "Test plan for different components developed in Sprint 23
",
"runs": [
{
"title": "User Authentication Module",
"assignmentId": 3,
"queryPlans": [{ "tcaseIds": ["1CEPaUhgH_Tvt2LZygwVRQa", "1CAPaUhgH_Tvt2LZygwVRTb"] }]
},
{
"title": "Payment Processing Module",
"assignmentId": 4,
"queryPlans": [{ "tcaseIds": ["1EEPaUhgH_Tvt2LZygwVRLm", "1FEPaUhgH_Tvt2LZygwVRNn"] }]
},
{
"title": "Notification Service",
"assignmentId": 5,
"queryPlans": [{ "tcaseIds": ["1GEPaUhgH_Tvt2LZygwVROo", "1HEPaUhgH_Tvt2LZygwVRPp"] }]
}
]
}
```
**Best Practices**
* **Configuration-Based Runs**: Most test plans will have runs with similar titles and identical test cases, differing only in configurations (e.g., browsers, devices, environments)
* **Consistent Naming**: Use a consistent naming pattern for runs testing the same functionality across configurations (e.g., "Feature X - Chrome", "Feature X - Firefox")
* **Same Test Cases**: Reuse the same test case IDs across runs when testing across different configurations
* **Assign by Expertise**: When testing across platforms, assign runs based on platform expertise rather than feature expertise
* **Link to Milestones**: Associate plans with milestones for better release tracking
* **Exception Cases**: Only create runs with different test cases when testing distinct components or modules
**Limitations**
* Each run must have exactly one query plan
* Only User selection test runs are supported (tcaseIds must be specified). See [Types of Runs](https://qasphere.com/docs/api/run#types-of-runs) for more details.
* Dynamic folder/tag-based selection is not available for plans
* Test plans cannot be cloned via the public API (planned for future release)
* Updating test plans is not yet available via the public API
## Related Resources
* [Runs](https://qasphere.com/docs/api/run) - Learn about individual test runs
* [Test Cases](https://qasphere.com/docs/api/tcases) - Manage test cases
* [Milestones](https://qasphere.com/docs/api/milestone) - Work with project milestones
* [Results](https://qasphere.com/docs/api/result) - Add results to test cases in runs
---
# Projects
URL: /docs/api/projects
The projects endpoint allows you to retrieve projects in your account.
## Authentication
Project visibility will depend if the user has proper access to the project. If you are the owner or an admin, you may grant access to users to a project
by going to your QA Sphere account, then go to the Members page in settings to grant access to the user.
## List Projects
`GET /api/public/v0/project`
Returns a list of all projects.
### Response
Status: 200 OK
```typescript
{
projects: Array<{
// A list of projects
id: string // Unique identifier for the project
code: string // User specified unique identifier for the project
title: string // Name of the project
description: html // Description of the project (Deprecated: use overviewDescription)
overviewTitle: string // Overview title shown in overview page of the project
overviewDescription: html // Overview description shown in overview page of the project
links: Array<{
// A list of links that is shown in the overview page of the project
url: string // URL of the link
text: string // Displayed text of the link
}>
createdAt: Date // Date when the project is created
updatedAt: Date // Date when project information was last updated
archivedAt: Date | null // Date when the project has been archived
}>
}
```
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project
```
### Example Response
```json
{
"projects": [
{
"id": "1CJo8oDjj_vkGo2rQAdzz4F",
"code": "BD",
"title": "Bistro Delivery",
"description": "Welcome to the Bistro Delivery 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.
",
"overviewTitle": "Bistro Delivery - Example",
"overviewDescription": "Welcome to the Bistro Delivery 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.
",
"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
}
]
}
```
### Error Responses
| Status Code | Description |
| ----------- | -------------------------------------------- |
| 500 | Internal server error during project listing |
## Get Project
`GET /api/public/v0/project/{project_code_or_id}`
Returns the project identified by code or id.
### Response
Status: 200 OK
```typescript
{
id: string // Unique identifier for the project
code: string // User specified unique identifier for the project
title: string // Name of the project
description: html // Description of the project (Deprecated: use overviewDescription)
overviewTitle: string // Overview title shown in overview page of the project
overviewDescription: html // Overview description shown in overview page of the project
links: Array<{
// A list of links that is shown in the overview page of the project
url: string // URL of the link
text: string // Displayed text of the link
}>
createdAt: Date // Date when the project is created
updatedAt: Date // Date when project information was last updated
archivedAt: Date | null // Date when the project has been archived
}
```
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD
```
### Example Response
```json
{
"id": "1CJo8oDjj_vkGo2rQAdzz4F",
"code": "BD",
"title": "Bistro Delivery",
"description": "Welcome to the Bistro Delivery 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.
",
"overviewTitle": "Bistro Delivery - Example",
"overviewDescription": "Welcome to the Bistro Delivery 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.
",
"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
}
```
### Error Responses
| Status Code | Description |
| ----------- | --------------------------------------------- |
| 403 | User has no permission to access project |
| 404 | Project not found |
| 500 | Internal server error during project fetching |
## Create Project
`POST /api/public/v0/project`
Creates a new project. Only users with role Admin or Owner are allowed to create a project.
### Request Body
```typescript
{
code: string // Unique project code (2-5 alphanumeric characters)
title: string // Name of the project (max 255 characters)
links?: Array<{ // Optional list of links for the project overview
url: string // URL of the link (max 255 characters)
text: string // Displayed text of the link (max 255 characters)
}>
overviewTitle?: string // Optional overview title (max 255 characters)
overviewDescription?: html // Optional overview description
}
```
### Example Request
```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": "Welcome to the Bistro Delivery example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process.
"
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project
```
### Response Fields
```typescript
{
id: string // Unique identifier for the project
}
```
### Example Response
Status: 201 Created
```json
{
"id": "1CJo8oDjj_vkGo2rQAdzz4F"
}
```
### Error Responses
| Status Code | Description |
| ----------- | --------------------------------------------- |
| 400 | Invalid project code format |
| 403 | User does not have admin permission |
| 409 | Project with the same title already exists |
| 500 | Internal server error during project creation |
---
# Requirements
URL: /docs/api/requirements
The requirements endpoints allow you to retrieve requirements that are linked to test cases within a project. Requirements help track traceability between test cases and external specifications, user stories, or other documentation.
## About Requirements
Requirements are references to external documentation or specifications that test cases are designed to verify. They consist of:
1. **Text**: A descriptive label for the requirement (1-255 characters)
2. **URL** (optional): A link to the external requirement document or issue tracker
Requirements can be linked to multiple test cases, and a single test case can be linked to multiple requirements. This enables full traceability between your tests and the specifications they validate.
* Requirements can be linked to external issues when a Jira or Linear integration is configured for the project
* Use `include=tcaseCount` to see how many test cases are linked to each requirement
* Requirements without any linked test cases are still returned in the list
## List Requirements
`GET /api/public/v0/project/{project_id}/requirement`
Retrieves all requirements within a project, optionally sorted and with additional fields included.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Query Parameters
All query parameters are optional.
| Parameter | Type | Description | Allowed Values | Example |
| ----------- | ------ | ---------------------------------------------------------------------- | -------------------- | -------------------- |
| `sortField` | string | Field to sort by | `created_at`, `text` | `sortField=text` |
| `sortOrder` | string | Sort order (requires `sortField`; default: `desc`) | `asc`, `desc` | `sortOrder=asc` |
| `include` | string | Include additional fields in the response which are omitted by default | `tcaseCount` | `include=tcaseCount` |
* Use `include=tcaseCount` to see how many test cases are linked to each requirement
* Sorting by `created_at` shows the most recently created requirements first (with `desc`) or oldest first (with `asc`)
* Sorting by `text` provides alphabetical ordering
### Example Request
#### Fetch all requirements
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement
```
#### Fetch all requirements sorted by text in ascending order
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement?sortField=text&sortOrder=asc
```
#### Fetch all requirements with test case count included
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement?include=tcaseCount
```
### Response Fields
```typescript
{
requirements: Array<{
// List of requirement objects
id: string // Unique identifier of the requirement (HQID7 format)
text: string // Descriptive label for the requirement
url: string // URL to the external requirement document (empty string if not set)
integrationLink?: {
// Integration link (only present if linked to Jira or Linear)
type: string // Integration type ("jira" or "linear")
integrationId: string // ID of the integration configuration
issueId: string // Internal issue ID (Jira numeric ID or Linear UUID)
issueTitle: string // Title of the linked issue
issueUrl: string // Full URL to the linked issue
remoteLinkId: string // Remote link/attachment ID in the external system
}
tcaseCount?: number // Number of test cases linked to this requirement (only included if requested)
}>
}
```
### Example Response
```json
{
"requirements": [
{
"id": "1CKgJ5HMU_1VQTDrRJDdDVW",
"text": "User Authentication",
"url": "https://docs.example.com/specs/auth",
"tcaseCount": 5
},
{
"id": "1CKgJ5HMU_2BJje4hdXZHag",
"text": "PROJ-456: Implement password reset functionality",
"url": "https://jira.example.com/browse/PROJ-456",
"integrationLink": {
"type": "jira",
"integrationId": "1CTPNLhFU_rPbCr23CbqftL",
"issueId": "10456",
"issueTitle": "Implement password reset functionality",
"issueUrl": "https://jira.example.com/browse/PROJ-456",
"remoteLinkId": "12345"
},
"tcaseCount": 3
},
{
"id": "1CKgJ5HMU_3apSDSQWRw6Ys",
"text": "Performance Requirements",
"url": ""
}
]
}
```
---
# Results
URL: /docs/api/result
The results endpoint allows you to add results for test cases in runs. Only users with role test runner or with higher privileges, having access to a project can add results.
Each test case result is assigned a status reflecting the outcome of its execution. QA Sphere supports several common statuses: `passed`, `failed`, `blocked`, `skipped`, and `open`. If you require additional statuses, QA Sphere allows you to create up to four custom statuses. These custom statuses can be used in the results as `custom1`, `custom2`, `custom3`, `custom4`. For more information on viewing and updating custom statuses using public APIs, please refer to the [Settings](https://qasphere.com/docs/api/settings) page.
You can also attach links to external issues created in integrations configured for the project. If the corresponding issue ID/key is provided in the meta information, QA Sphere will add a comment on the issue for non-custom integrations (GitHub, Jira, Linear) to create a bi-directional reference:
* **GitHub/Jira**: Issue number (e.g., `"123"`)
* **Linear**: Issue key (e.g., `"PRJ-123"`)
Public result endpoints support integration links only. They do not accept uploaded file attachments.
## Add Result
`POST /api/public/v0/project/{project_id}/run/{run_id}/tcase/{tcase_or_legacy_id}/result`
Add result for a run test case.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
* `run_id`: The run identifier
* `tcase_or_legacy_id`: The test case identifier (can be one of test case UUID, sequence or legacy ID)
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Request Body
```typescript
{
status: string // Required: Result status ("passed" | "failed" | "blocked" | "skipped" | "open" | "custom1" | "custom2" | "custom3" | "custom4")
comment: html // Required: Comments/observations while executing the test case
timeTaken?: number // Optional: Time taken for executing the test case
links?: Array<{ // Optional: Links to issues on external integration to attach to this result
integrationId: string // Required: Unique identifier of the project integration
url: string // Required: URL of the external issue
text: string // Required: Title of the external issue
meta?: { // Optional: Additional information related to the issue (for non-custom integrations)
id?: string // Optional: Issue ID/key used to add a comment on the external issue linking back to this result
}
}>
}
```
### Response Fields
| Field | Type | Description |
| ----- | -------- | -------------------------------- |
| `id` | `number` | Unique identifier for the result |
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"status": "failed",
"comment": "Login page background color is not correct
",
"links": [{
"integrationId": "1CSWAh3ys_YniqfXepnwT8F",
"url": "https://external-integration/issues/1",
"text": "Login page background color is not correct"
}],
"timeTaken": 60
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/tcase/1/result
```
### Example Response
```json
{
"id": 10
}
```
### Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------------------------- |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant or project is archived |
| 404 | Project or test run or test case not found |
| 409 | Test run is closed |
| 500 | Internal server error while adding result |
## Add Multiple Results
`POST /api/public/v0/project/{project_id}/run/{run_id}/result/batch`
Add results for multiple test cases in a run.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
* `run_id`: The run identifier
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Request Body
```typescript
{
items: Array<{
// Required: List of result items
tcaseId: string // Required: The unique identifier of the test case
status: string // Required: Result status ("passed" | "failed" | "blocked" | "skipped" | "open" | "custom1" | "custom2" | "custom3" | "custom4")
comment: html // Required: Comments/observations while executing the test case
timeTaken?: number // Optional: Time taken for executing the test case
links?: Array<{
// Optional: Links to issues on external integration to attach to this result
integrationId: string // Required: Unique identifier of the external integration
url: string // Required: URL of the external issue
text: string // Required: Title of the external issue
meta?: {
// Optional: Additional information related to the issue (for non-custom integrations)
id?: string // Optional: Issue ID/key used to add a comment on the external issue linking back to this result
}
}>
}>
}
```
### Response Fields
| Field | Type | Description |
| ----- | ---------- | --------------------------------------------------------------------- |
| `ids` | `number[]` | List of IDs for the created results, in the same order as the request |
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"tcaseId": "1CSm3erpq_Ykq6AVPRrLYd1",
"status": "failed",
"comment": "Login page background color is not correct
",
"links": [{
"integrationId": "1CSWAh3ys_YniqfXepnwT8F",
"url": "https://external-integration/issues/1",
"text": "Login page background color is not correct"
}],
"timeTaken": 60
},
{
"tcaseId": "1CSaE4bJE_mHke3r3yJRAgk",
"status": "passed",
"comment": ""
},
{
"tcaseId": "1CSaDwU7T_FKcgke4dVwJNP",
"status": "custom3",
"comment": "Page failed to load
",
"links": [{
"integrationId": "1CSWAh3ys_YniqfXepnwT8F",
"url": "https://external-integration/issues/1",
"text": "Page failed to load"
}]
}
]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/result/batch
```
### Example Response
```json
{
"ids": [11, 12, 13]
}
```
### Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------------------------- |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant or project is archived |
| 404 | Project or test run not found |
| 409 | Test run is closed |
| 500 | Internal server error while adding result |
**Validation**
The system validates that the run belongs to the project, test case belongs to the run, the project is not archived and the run is not closed. Attempting to add result which does not satisfy these validations will result in an error.
---
# Runs
URL: /docs/api/run
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. Write operations (create/update/delete) can only be performed by users with role test runner or with higher privileges.
## 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 versioned test case properties, such as title and steps, are reflected for test cases with 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 versioned test case properties, such as title and steps, are not reflected in the run, even for test cases with 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
* Updates to versioned test case properties, such as title and steps, are reflected for test cases with open statuses
1. Updates to test cases are never propagated to closed runs
2. For live and user selection runs, test case versions are fixed once the status is non-open. As a result, updates to versioned test case properties, such as title and steps, are not reflected in the run
3. Changes to the folder and position of test cases are always propagated to all run types, except closed runs, because these changes are not versioned. This means that such updates do not create a new test case version and are applied to all existing versions of the test case
## Test Case Selection
Test cases can be selected in two ways:
1. **Direct Selection**: Use `tcaseIds` to directly specify the test cases
2. **Using filters**:
* `folderIds`: Select test cases from specific folders, including those within subfolders
* `tagIds`: Select test cases with specific tags
* `priorities`: Select test cases with specific priority levels
* If any of these filters is not specified or is left empty, all test cases are selected without filtering based on that criterion
* The resulting list of test cases is obtained by applying a logical AND to these conditions
This selection method is referred to as a **Query Plan**.
* For static and user selection runs, only single query plan can be specified. When using filters, the system automatically resolves them to a fixed set of test cases at the time of creation
* For live runs, only filter-based selection is allowed, and multiple query plans can be specified. The results of all query plans are combined using a union to create the final list of test cases. Additionally, as test case properties change, test cases are automatically added to or removed from the run according to the query plans
1. Only `standalone` and `filled` test case types are allowed in a 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` |
| `include` | Return only the specified related objects (all are returned when omitted) | `include=configuration&include=statusCounts` |
By default every related object listed under [Response Fields](#response-fields) is returned. Supply one or more `include` values to return **only** the related objects you need — any related object you do not list is returned as `null`. Allowed values: `project`, `plan`, `milestone`, `assignment`, `configuration`, `statusCounts`.
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run
```
### Response Fields
```typescript
{
runs: Array<{
id: number // Unique identifier of the test run
type: string // Type of the run (`static` | `static_struct` | `live`)
title: string // Title of the test run
description: html // Description of the test run
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
}
planId: number | null // ID of the test plan to which the run belongs to (if any)
plan: {
// Test plan details (if any)
title: string // Test plan title
} | null
milestoneId: number | null // ID of associated milestone (if any)
milestone: {
// Milestone details (if any)
title: string // Milestone Title
} | null
assignmentId: number | null // ID of the assigned user (if any)
assignment: {
// Assignee details (if any)
id: number // User ID
email: string // User email
name: string // User display name
avatar: string // URL to user's avatar; fetching it requires authentication
role: string // User role in the project
} | null
configurationId: number | null // ID of the configuration associated with the run (if any)
configuration: {
// Configuration details (if any)
id: string // Configuration ID
title: string // Configuration title
createdAt: string // Configuration creation timestamp
updatedAt: string // Configuration last update timestamp
} | null
statusCounts: {
// Count of run 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
custom1: number // Count of test cases with first custom status
custom2: number // Count of test cases with second custom status
custom3: number // Count of test cases with third custom status
custom4: number // Count of test cases with fourth custom status
}
timeSpent: number | null // Time spent on the run
isAutomated: boolean // Whether the run was created using public APIs
createdAt: string // Run creation timestamp
closedAt: string | null // Run 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.
1. For `static`/`static_struct` run types:
* Only a single query plan should be specified, and either of the two selection methods (direct or filters) can be used
* When using filters, the system automatically resolves them to a fixed set of test cases at the time of creation
2. For `live` run types, only filter-based selection is permitted, and multiple query plans can be specified
3. Within a given query plan, the filter conditions are combined using a logical AND
4. The test case lists obtained from different query plans are combined using a union
5. Only `standalone` and `filled` test case types are allowed in a run
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Request Body
```typescript
{
title: string // Required: Run title
description?: html // Optional: Run description
type: string // Required: Run type (`static` | `static_struct` | `live`)
milestoneId?: number // Optional: Associated milestone
configurationId?: string // Optional: Associated configuration
assignmentId?: number // Optional: Assigned user
queryPlans: Array<{ // Required: Test case selection criteria
// Direct Selection:
tcaseIds?: Array // Directly specify test cases
// Using Filters:
folderIds?: Array // Select test cases from folders (including subfolders)
tagIds?: Array // Select test cases with tags
priorities?: Array // Select by priority (`low` | `medium` | `high`)
}>
}
```
**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 is allowed
* For live runs: Only filter based selection is allowed
* `milestoneId`: The milestone must belong to the project and must not be archived
* `assignmentId`: Must be an active user with permissions above Viewer role
### Example Request - Live Run With Filtered Test Cases
```bash
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"]
}, {
"folderIds": [4, 6],
"tagIds": [],
"priorities": ["medium", "high"]
}]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run
```
### Example Request - Live Run With All Test Cases
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"title": "Complete Test Suite",
"description": "Run with all test cases from the project
",
"type": "live",
"milestoneId": 5,
"queryPlans": [{
"folderIds": [],
"tagIds": [],
"priorities": []
}]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run
```
### Example Request - Static Run With Specific Test Cases
```bash
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
```json
{
"id": 2
}
```
**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
## 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.
The support for cloning runs with test plans via this endpoint is planned for a future release.
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Request Body
```typescript
{
runId: number // Required: Source run ID to clone
title: string // Required: New run title
description?: html // 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`: The milestone must belong to the project and must not be archived
* `assignmentId`: Must be an active user with permissions above Viewer role
### Example Request
```bash
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
```json
{
"id": 2
}
```
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
## Close Run
`POST /api/public/v0/project/{project_id}/run/{run_id}/close`
Close an open test run.
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/close
```
## 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
All query parameters are optional and some can be specified multiple times using the format `param=value1¶m=value2¶m=value3`.
| Parameter | Type | Multiple | Description | Allowed Values | Example |
| -------------------------------- | ------ | -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------- |
| `search` | string | no | Filter test cases by title (case insensitive, partial matches) | | `search=ui` |
| `tags` | number | yes | Filter test cases by tag ID | | `tags=12` |
| `priorities` | string | yes | Filter test cases by priority | `high`, `medium`, `low` | `priorities=low` |
| `include` | string | yes | Include additional fields in the response which are omitted by default | `folder`, `steps`, `tags`, `precondition`, `requirements`, `customFields` | `include=steps` |
| `cf_${custom field system name}` | string | yes | Filter test cases by custom field value | Custom field defined values | `cf_automation=Automated` |
* Different filters are combined with AND logic
* Multiple values for the same filter are combined with OR logic
* `include=steps`, `include=tags`, `include=precondition`, `include=requirements` and
`include=customFields` return the content of the exact test case version pinned by the
run, so the response matches what the run's results were recorded against even if a
test case was edited later. The
[Test Cases list endpoint](/docs/api/endpoints/tcases) always returns the latest version instead.
### Example Request
#### Fetch all run test cases with additional folder information
```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?include=folder
```
#### Fetch all run test cases with their steps and tags in a single request
```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?include=steps&include=tags"
```
#### Fetch all test cases from a run with "Automation" custom field to be "Automated"
```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?cf_automation=Automated
```
#### Fetch 20 test cases from a run sorted by title in ascending order
```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?limit=20&sortField=title&sortOrder=asc
```
#### Fetch 10 most recent added test cases from a run
```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?limit=10&sortField=created_at&sortOrder=desc
```
#### Fetch test cases with "backend" in their title from a run
```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?search=backend
```
#### Fetch test cases with tag "cart" from a run
```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?tag=cart
```
#### Fetch test cases with priority "high" from a run
```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?priority=high
```
### Response Fields
```typescript
{
tcases: Array<{
id: string // Unique identifier of the test case
version: number // Version number of the test case
legacyId: string // Legacy identifier (if any)
type: string // Type of the test case (`standalone` | `filled`)
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 // Status of the latest result added for the run test case (open if no results are added)
isAutomated: boolean // Whether latest result was added using public APIs
isEmpty: boolean // Whether the test case is empty (has no comment and steps)
templateTCaseId?: string // Corresponding template test case ID, if it is a filled test case
folder?: {
// Folder information if include=folder query parameter is passed
id: number // Unique identifier for the folder
parentId: number // Unique identifier of the parent of the folder (0 if it is the root folder)
title: string // Title of the folder
comment: html // Added comment for the folder
pos: number // Position of the folder with respect to its sibling (starts with 0)
}
steps?: Array // Steps of the pinned test case version if include=steps is passed
// (same shape as `steps` in the Get Run Test Case response below)
tags?: Array<{
// Tags of the pinned test case version if include=tags is passed
id: number // Unique identifier of the tag
title: string // Title of the tag
}>
precondition?: {
// Precondition of the pinned test case version if include=precondition is passed
projectId: string // Project id the precondition belongs to
id: number // Unique identifier of the precondition
version: number // Version of the precondition
type: string // Type of the precondition (standalone | shared)
title?: string // Title of the precondition (only for shared preconditions)
text: html // Text of the precondition (empty when the test case has none)
isLatest: boolean // Whether this is the latest version of the precondition
}
requirements?: Array<{
// Requirements of the pinned test case version if include=requirements is passed
id: string // Unique identifier of the requirement
text: string // Title of the requirement
url: string // URL of the requirement
}>
customFields?: {
// Custom fields of the pinned test case version if include=customFields is passed
[key: string]: {
// Key-value pairs of custom field system names and corresponding details
value: string // Current value
isDefault: boolean // Whether default value is set by the system or selected by the user
}
}
}>
}
```
### Sample Response
```
{
"tcases": [
{
"id": "1CGeNaNVt_Axa7TcMjUm6Zh",
"version": 1,
"legacyId": "",
"type": "standalone",
"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,
"isEmpty": true
},
{
"id": "1CGeNaNWP_Eiq5mjzPsKSX9",
"version": 1,
"legacyId": "",
"type": "filled",
"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,
"isEmpty": false
}
]
}
```
## Get Run Test Case
`GET /api/public/v0/project/{project_id}/run/{run_id}/tcase/{tcase_or_legacy_id}`
Get details of a single run test case using its ID, sequence or legacy ID.
Step `data` items follow the shape described in the Step Test Data section of the [Test Cases](/docs/api/tcases/#step-test-data) page.
### Example Request
```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
```
### Response Fields
```typescript
{
id: string // Unique identifier of the test case
version: number // Version number of the test case
legacyId: string // Legacy identifier (if any)
type: string // Test case type (`standalone` | `filled`)
title: string // Title of the test case
seq: number // Sequence number of the test case
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`)
templateTCaseId: string | null // Identifier of the parent template test case (in case of `filled` test case type)
comment: html // Test case precondition
steps: Array<{ // List of test case steps
id: number // Unique identifier of the step
type: string // Type of the step (standalone | shared)
version: number // Version of the step (always 1 for standalone steps)
isLatest: boolean // Whether this is the latest version of the step (always true for standalone steps)
title?: string // Title of the step (only for shared steps)
subSteps?: Array<{ // List of sub steps (only for shared steps)
id: number // Unique identifier of the step
type: string // Type of the step (shared_sub_step)
version: number // Version of the step (same as parent step)
isLatest: boolean // Whether this is the latest version (same as parent step)
description: html // Details of the sub step
expected: html // Expected result from the sub step
data?: Array // Sub step test data items (see Step Test Data on the Test Cases page)
deletedAt?: string // Date the sub step was deleted on
}>
description?: html // Details of step (only for standalone steps)
expected?: html // Expected result from the step (only for standalone steps)
data?: Array // Step test data items, only for standalone steps (see Step Test Data)
deletedAt?: string // Date the step was deleted on
}>
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
}>
customFields: { // Custom fields defined for the test case
[key: string]: { // Key-value pairs of custom field system names and corresponding details for the test case
value: string // Current value
isDefault: boolean // Whether default value is set by the system or selected by the user
}
}
authorId: number // Unique identifier of the user who created the test case
createdAt: string // Test case creation timestamp (ISO 8601 format)
status: string // Status of the latest result added for the run test case (open if no results are added)
isAutomated: boolean // Whether latest result was added using public APIs
isLatestVersion: boolean // Whether this is the latest version of the test case
isEmpty: boolean // Whether the test case is empty (has no comment and steps)
templateTCaseId?: string // Corresponding template test case ID, if it is a filled test case
results: Array<{ // Results created for this test case in the run
id: number // Unique identifier of the test case result
tcaseId: string // Unique identifier of the test case
tcaseVersion: string // Version number of the test case
authorId: number // Unique identifier of the user who added the result
author: { // Details of the user who added the result
id: number // Unique identifier of the user
email: string // Email of the user
name: string // Name of the user
avatar: string | null // Avatar URL of the user; fetching it requires authentication
role: string // Role of the user (`owner` | `admin` | `user` | `test-runner` | `viewer`)
}
status: string // Result status (`passed` | `failed` | `blocked` | `skipped` | `open` | `custom1` | `custom2` | `custom3` | `custom4`)
comment: html // Comments/observations while executing the test case
links: Array<{ // Details of issues created in external integrations
id: number // Unique identifier of the issue
resultId: number // Unique identifier of the result for which the issue is created
integrationId: string // Unique identifier of the external integration on which the issue is created
integration: { // Details of the external integration
id: string // Unique identifier of the integration
name: string // Name of the integration
type: string // Integration type (`jira` | `github` | `custom`)
config: object // Configuration for the integration (eg. url/email)
}
url: string // URL of the created issue
text: string // Title of the created issue
meta: object // Additional information related to the issue
}>
timeTaken: number | null // Time taken for executing the test case
apiKeyId: string | null // Unique identifier of the API key, if this result was added via public APIs
internal: boolean // Whether the result was added by system (eg. when test run is modified)
createdAt: string // Result creation time (ISO 8601 format)
}>
}
```
### Sample Response
```json
{
"id": "1CEPaUhgH_Tvt2LZygwVRQa",
"version": 1,
"legacyId": "",
"type": "standalone",
"title": "Changing to corresponding cursor after hovering the element",
"seq": 1,
"folderId": 2,
"pos": 0,
"priority": "low",
"templateTCaseId": null,
"comment": "The \"About Us\" page is opened
",
"steps": [
{
"description": "Test the display across various screen sizes (desktop, tablet, mobile) to ensure that blocks and buttons adjust appropriately to different viewport widths
",
"expected": ""
}
],
"tags": [
{
"id": 1,
"title": "About Us"
},
{
"id": 2,
"title": "Checklist"
}
],
"files": [],
"requirements": [],
"links": [],
"customFields": {},
"authorId": 1,
"createdAt": "2024-01-01T00:00:00.000Z",
"status": "open",
"isAutomated": false,
"isLatestVersion": true,
"isEmpty": false,
"results": [
{
"id": 20293,
"tcaseId": "1CEPaUhgH_Tvt2LZygwVRQa",
"tcaseVersion": 1,
"authorId": 1,
"author": {
"id": 1,
"email": "owner@example.com",
"name": "System Owner",
"avatar": null,
"role": "owner"
},
"status": "blocked",
"comment": "",
"links": null,
"timeTaken": null,
"apiKeyId": null,
"internal": false,
"createdAt": "2024-01-01T00:00:00.000Z"
}
]
}
```
## Create Run Log
`POST /api/public/v0/project/{project_id}/run/{run_id}/log`
Create a log entry for a test run. Run logs can be used to record messages from CI/CD pipelines, automation frameworks, or any external system during test execution. Logs cannot be added to closed runs.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
* `run_id`: The run identifier (numeric)
### Authentication
Requires an API key with at least Test Runner role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Request Body
```typescript
{
comment: string // Required: Log message content (HTML supported, minimum 1 character)
}
```
**Field Constraints**
* `comment`: Must be at least 1 character long. HTML content is sanitized and leading/trailing whitespace is trimmed.
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"comment": "Build #1234 failed: 3 test cases did not pass
"
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/run/1/log
```
### Response Fields
| Field | Type | Description |
| ----- | -------- | --------------------------------- |
| `id` | `string` | Unique identifier for the run log |
### Example Response
Status: 201 Created
```json
{
"id": "1CGeNaNVt_Axa7TcMjUm6Zh"
}
```
### Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------------------------- |
| 400 | Invalid request body or empty comment |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant or project is archived |
| 404 | Project or test run not found |
| 409 | Test run is closed |
| 500 | Internal server error while creating log |
---
# Settings
URL: /docs/api/settings
The settings endpoint allows you to check and update result statuses.
## Result Status
Each test case result is assigned a status based on the outcome of its execution. QA Sphere supports two categories of statuses:
1. **Default Statuses**: These are the commonly used statuses that come by default. They include `passed`, `failed`, `blocked`, `skipped`, and `open`. These statuses cannot be removed or modified.
2. **Custom Statuses**: If additional statuses are needed, QA Sphere allows for the creation of up to four custom statuses. The labels and colors for these custom statuses can be configured and will be displayed in the UI. In the API, these statuses are referred to as `custom1`, `custom2`, `custom3`, and `custom4`.
## Get Statuses
`GET /api/public/v0/settings/preferences/status`
Get current status configuration.
### Response
Status: 200 OK
```typescript
{
statuses: Array<{
id: string // Unique identifier for the status ("passed" | "failed" | "blocked" | "skipped" | "open" | "custom1" | "custom2" | "custom3" | "custom4")
name: string // Display name of the status
color: string // Display color of the status ("blue" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "indigo" | "purple" | "pink")
isDefault: boolean // Is this a default status
isActive: boolean // Is this (custom) status enabled (always true for default statuses)
inUse: boolean // Is this (custom) status in use (always true for default statuses)
}>
}
```
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/settings/preferences/status
```
### Example Response
```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
}
]
}
```
### Error Responses
| Status Code | Description |
| ----------- | --------------------------------------------- |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 500 | Internal server error while fetching statuses |
## Update Custom Statuses
`POST /api/public/v0/settings/preferences/status`
Update custom statuses.
* Custom statuses apply across the entire account, and any updates will also be reflected in previously added results.
* Once a custom status is enabled and is in use, it cannot be disabled.
### Authentication
Requires an API key with at least Admin role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Request Body
```typescript
{
statuses: Array<{
id: string // Unique identifier for the custom status ("custom1" | "custom2" | "custom3" | "custom4")
name: string // Display name of the status
color: string // Display color of the status ("blue" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "indigo" | "purple" | "pink")
isActive: boolean // Is this custom status enabled
}>
}
```
### Response
Status: 200 OK
```typescript
{
message: 'Statuses updated'
}
```
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"statuses": [
{
"id": "custom3",
"name": "Blocker",
"color": "red",
"isActive": true
}
]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/settings/preferences/status
```
### Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------ |
| 400 | Invalid status id or color |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 409 | Trying to update default or in use custom status |
| 500 | Internal server error while updating statuses |
* Custom statuses can only be updated by users with owner or admin roles.
* Custom statuses apply across the entire account, and any updates will also be reflected in previously added results.
* Once a custom status is enabled and used, it cannot be disabled.
---
# Shared Preconditions
URL: /docs/api/shared_preconditions
The shared preconditions endpoints allow you to manage reusable test preconditions that can be referenced across multiple test cases. Shared preconditions consist of a title and text content that describes the initial state or setup required before executing test cases.
## About Shared Preconditions
Shared preconditions are reusable precondition templates that can be used in multiple test cases. They consist of:
1. **Title**: A descriptive name for the shared precondition (required, minimum 1 character)
2. **Text**: The actual precondition content in HTML format (required, minimum 1 character)
When a shared precondition is used in a test case, it provides consistent setup instructions. Updates to a shared precondition automatically propagate to all test cases that reference it.
* Shared preconditions must have both a title and text content
* The title of a shared precondition must be unique within a project
* Shared preconditions are versioned - updates create new versions while preserving old ones
* Deleted preconditions are marked with a `deletedAt` timestamp but remain in the data structure
## List Shared Preconditions
`GET /api/public/v0/project/{project_id}/shared-precondition`
Retrieves all shared preconditions within a project, optionally sorted and with additional fields included.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Query Parameters
All query parameters are optional.
| Parameter | Type | Description | Allowed Values | Example |
| ----------- | ------ | ---------------------------------------------------------------------- | --------------------- | -------------------- |
| `sortField` | string | Field to sort by | `created_at`, `title` | `sortField=title` |
| `sortOrder` | string | Sort order (requires `sortField`; default: `desc`) | `asc`, `desc` | `sortOrder=asc` |
| `include` | string | Include additional fields in the response which are omitted by default | `tcaseCount` | `include=tcaseCount` |
* Use `include=tcaseCount` to see how many test cases reference each shared precondition
* Sorting by `created_at` shows the most recently created preconditions first (with `desc`) or oldest first (with `asc`)
* Sorting by `title` provides alphabetical ordering
* If no `sortField` is specified, the default sort is by `title` in ascending order
### Example Request
#### Fetch all shared preconditions
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-precondition
```
#### Fetch all shared preconditions sorted by title in ascending order
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-precondition?sortField=title&sortOrder=asc
```
#### Fetch all shared preconditions sorted by creation date (newest first)
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-precondition?sortField=created_at&sortOrder=desc
```
#### Fetch all shared preconditions with test case count included
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-precondition?include=tcaseCount
```
### Response Fields
```typescript
Array<{
// List of shared precondition objects
projectId: string // Unique identifier of the project
id: number // Unique identifier of the shared precondition
version: number // Version of the shared precondition
title: string // Title of the shared precondition
type: string // Type of the precondition (always "shared" for shared preconditions)
text: html // Text content of the precondition (HTML format)
isLatest: boolean // Whether this is the latest version of the precondition
createdAt: string // Precondition creation time (ISO 8601 format)
updatedAt: string // Precondition updation time (ISO 8601 format)
deletedAt?: string // Date the precondition was deleted on (ISO 8601 format)
tcaseCount?: number // Number of test cases using this shared precondition (only included if requested)
}>
```
### Example Response
```json
[
{
"projectId": "2HKj57k3z_YXYQVTdnPqrs8",
"id": 1,
"version": 2,
"title": "User is logged in",
"type": "shared",
"text": "The user has valid credentials and is authenticated in the system
",
"isLatest": true,
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-20T14:45:00.000Z"
},
{
"projectId": "2HKj57k3z_YXYQVTdnPqrs8",
"id": 2,
"version": 1,
"title": "Application is running",
"type": "shared",
"text": "The application server is running and accessible
",
"isLatest": true,
"createdAt": "2025-01-16T09:15:00.000Z",
"updatedAt": "2025-01-16T09:15:00.000Z",
"tcaseCount": 15
},
{
"projectId": "2HKj57k3z_YXYQVTdnPqrs8",
"id": 3,
"version": 1,
"title": "Database is initialized",
"type": "shared",
"text": "The database contains the required test data
",
"isLatest": true,
"createdAt": "2025-01-17T11:20:00.000Z",
"updatedAt": "2025-01-17T11:20:00.000Z",
"tcaseCount": 3
}
]
```
## Get Shared Precondition
`GET /api/public/v0/project/{project_id}/shared-precondition/{shared_precondition_id}`
Get details of a single shared precondition using its ID.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
* `shared_precondition_id`: The shared precondition identifier (numeric ID)
### Example Request
```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
```
### Response Fields
```typescript
{
projectId: string // Unique identifier of the project
id: number // Unique identifier of the shared precondition
version: number // Version of the shared precondition
title: string // Title of the shared precondition
type: string // Type of the precondition (always "shared" for shared preconditions)
text: html // Text content of the precondition (HTML format)
isLatest: boolean // Whether this is the latest version of the precondition
createdAt: string // Precondition creation time (ISO 8601 format)
updatedAt: string // Precondition updation time (ISO 8601 format)
deletedAt?: string // Date the precondition was deleted on (ISO 8601 format)
}
```
### Example Response
```json
{
"projectId": "2HKj57k3z_YXYQVTdnPqrs8",
"id": 1,
"version": 2,
"title": "User is logged in",
"type": "shared",
"text": "The user has valid credentials and is authenticated in the system
",
"isLatest": true,
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-20T14:45:00.000Z"
}
```
---
# Shared Steps
URL: /docs/api/shared_steps
The shared steps endpoints allow you to manage reusable test steps that can be referenced across multiple test cases. Shared steps consist of a title and a list of sub-steps, each with a description and expected result.
## About Shared Steps
Shared steps are reusable test step templates that can be used in multiple test cases. They consist of:
1. **Title**: A descriptive name for the shared step (1-255 characters)
2. **Sub-steps**: A list of individual steps, each with:
* **Description**: What action to perform (HTML content)
* **Expected**: The expected result (HTML content)
* **Test data** (optional): A list of up to 20 test data items (`text`, `link`, or `file`), returned in the `data` field — see the Step Test Data section of the [Test Cases](/docs/api/tcases/#step-test-data) page for the item shape
When a shared step is used in a test case, all its sub-steps are included. Updates to a shared step automatically propagate to all test cases that reference it.
* Shared steps must have at least one sub-step
* Each sub-step must have at least a description, expected result, or test data
* The title of a shared step must be unique within a project
* Shared steps are versioned - updates create new versions while preserving old ones
* Deleted sub-steps are marked with a `deletedAt` timestamp but are not deleted because they may still be referenced by some test case versions
## List Shared Steps
`GET /api/public/v0/project/{project_id}/shared-step`
Retrieves all non deleted shared steps within a project, optionally sorted and with additional fields included.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Query Parameters
All query parameters are optional.
| Parameter | Type | Description | Allowed Values | Example |
| ----------- | ------ | ---------------------------------------------------------------------- | --------------------- | -------------------- |
| `sortField` | string | Field to sort by | `created_at`, `title` | `sortField=title` |
| `sortOrder` | string | Sort order (requires `sortField`; default: `desc`) | `asc`, `desc` | `sortOrder=asc` |
| `include` | string | Include additional fields in the response which are omitted by default | `tcaseCount` | `include=tcaseCount` |
* Use `include=tcaseCount` to see how many test cases reference each shared step
* Sorting by `created_at` shows the most recently created steps first (with `desc`) or oldest first (with `asc`)
* Sorting by `title` provides alphabetical ordering
### Example Request
#### Fetch all shared steps
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-step
```
#### Fetch all shared steps sorted by title in ascending order
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-step?sortField=title&sortOrder=asc
```
#### Fetch all shared steps with test case count included
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-step?include=tcaseCount
```
### Response Fields
```typescript
{
sharedSteps: Array<{
// List of shared step objects
id: number // Unique identifier of the shared step
version: number // Version of the shared step
type: string // Type of the step (always "shared" for shared steps)
title: string // Title of the shared step
isLatest: boolean // Whether this is the latest version of the step
subSteps: Array<{
// List of sub-steps
id: number // Unique identifier of the sub-step
type: string // Type of the step (always "shared_sub_step")
version: number // Version of the step (same as parent step)
isLatest: boolean // Whether this is the latest version (same as parent step)
description: html // Details of the sub-step
expected: html // Expected result from the sub-step
data?: Array // Sub-step test data items (see Step Test Data on the Test Cases page)
deletedAt?: string // Date the sub-step was deleted on (ISO 8601 format)
}>
deletedAt?: string // Date the shared step was deleted on (ISO 8601 format)
tcaseCount?: number // Number of test cases using this shared step (only included if requested)
}>
}
```
### Example Response
```json
{
"sharedSteps": [
{
"id": 1,
"version": 3,
"type": "shared",
"title": "User login validation",
"isLatest": true,
"subSteps": [
{
"id": 2,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Navigate to the login page
",
"expected": "Login form is displayed
"
},
{
"id": 3,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Enter valid username and password
",
"expected": "Credentials are accepted
"
},
{
"id": 4,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Click the login button
",
"expected": "User is redirected to the dashboard
"
}
]
},
{
"id": 5,
"version": 1,
"type": "shared",
"title": "Form submission validation",
"isLatest": true,
"subSteps": [
{
"id": 6,
"type": "shared_sub_step",
"version": 1,
"isLatest": true,
"description": "Fill in all required fields
",
"expected": "All fields are populated correctly
"
},
{
"id": 7,
"type": "shared_sub_step",
"version": 1,
"isLatest": true,
"description": "Submit the form
",
"expected": "Form is submitted successfully
"
}
],
"tcaseCount": 12
}
]
}
```
## Get Shared Step
`GET /api/public/v0/project/{project_id}/shared-step/{step_id}`
Get details of a single shared step using its ID.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
* `step_id`: The shared step identifier (numeric ID)
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/shared-step/1
```
### Response Fields
```typescript
{
id: number // Unique identifier of the shared step
version: number // Version of the shared step
type: string // Type of the step (always "shared" for shared steps)
title: string // Title of the shared step
isLatest: boolean // Whether this is the latest version of the step
subSteps: Array<{ // List of sub-steps
id: number // Unique identifier of the sub-step
type: string // Type of the step (always "shared_sub_step")
version: number // Version of the step (same as parent step)
description: html // Details of the sub-step
expected: html // Expected result from the sub-step
data?: Array // Sub-step test data items (see Step Test Data on the Test Cases page)
deletedAt?: string // Date the sub-step was deleted on (ISO 8601 format)
}>
isLatest: boolean // Whether this is the latest version (same as parent step)
deletedAt?: string // Date the shared step was deleted on (ISO 8601 format)
}
```
### Example Response
```json
{
"id": 1,
"version": 3,
"type": "shared",
"title": "User login validation",
"isLatest": true,
"subSteps": [
{
"id": 2,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Navigate to the login page
",
"expected": "Login form is displayed
"
},
{
"id": 3,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Enter valid username and password
",
"expected": "Credentials are accepted
",
"data": [
{
"type": "text",
"label": "Credentials",
"data": { "value": "user@example.com / s3cret", "format": "plaintext" }
}
]
},
{
"id": 4,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Click the login button
",
"expected": "User is redirected to the dashboard
"
}
]
}
```
---
# Tags
URL: /docs/api/tag
Tags help organize and categorize test cases within your project. You can use tags in query plans to filter test cases when creating runs.
## List Project Tags
`GET /api/public/v0/project/{project_id}/tag`
Returns all tags defined in the project. This endpoint is particularly useful when creating run query plans that filter test cases by tags.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Response
Status: 200 OK
```typescript
{
tags: Array<{
id: number // Unique tag identifier within the project
title: string // Tag name/label
}>
}
```
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tag
```
### Example Response
```json
{
"tags": [
{
"id": 1,
"title": "regression"
},
{
"id": 2,
"title": "api-tests"
},
{
"id": 3,
"title": "smoke-tests"
}
]
}
```
### Error Responses
| Status Code | Description |
| ----------- | -------------------------------------------- |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 404 | Project not found |
| 500 | Internal server error |
### Using Tags in Run Query Plans
Tags returned by this endpoint can be used in run query plans to filter test cases. For example:
```json
{
"title": "API Regression Run",
"type": "live",
"queryPlans": [
{
"folderIds": [1],
"tagIds": [2], // Using the tag ID for "api-tests"
"priorities": ["high"]
}
]
}
```
Tag IDs are unique within a project but not across projects. Always verify you're using tag IDs from the correct project.
**Using Multiple Tags**
You can include multiple tag IDs in a query plan to select test cases that have any of the specified tags.
```json
{
"tagIds": [2, 3] // Selects test cases with either "api-tests" or "smoke-tests" tags
}
```
---
# Test Cases
URL: /docs/api/tcases
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:
1. **Standalone Test Case**: These are the standard test cases.
2. **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.
3. **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.
* 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.
## Step Test Data
Each standalone step (and each sub-step of a shared step) can carry a list of test data items in its `data` field. Every item is one of three types, discriminated by `type`:
```typescript
{
type: string // Required: `text` | `link` | `file`
label?: string // Optional: Item label (max 255 characters, trimmed)
data: // Required: Value, shape depends on `type`
| { value: string, format?: string } // text: required content (max 65535 UTF-16 code units) with an optional language hint (max 32 characters; see below)
| { value: string } // link: an http(s) URL (max 255 characters)
| { value: File } // file: a file object (`id`, `fileName`, `mimeType`, `size`, `stableUrl`, `url`), same shape as test case `files`
}
```
* A step can have at most 20 test data items.
* `text` items must have a non-empty `value` of at most 65,535 UTF-16 code units. `format` is a language hint for syntax highlighting (e.g. `plaintext`, `json`, `sql`); an unsupported value falls back to plain text.
* For `file` items, upload the file first using the upload file endpoint, then pass the object it returns as the item's `value`.
* A step is kept when it has a description, an expected result, **or** test data, so a step carrying only `data` is valid.
* Test data belongs to standalone steps and to shared step sub-steps. A step that references a shared step by `sharedStepId` must not send `data` — the shared step owns the data on its sub-steps, and sending both is rejected.
* Shared steps and their test data are managed through the web UI; the public API returns sub-step `data` in read responses.
## 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¶m=value2¶m=value3`.
| Parameter | Type | Multiple | Description | Allowed Values | Example |
| -------------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `offset` | number | no | Number of rows to skip before returning results. Combine with `limit` for offset-based pagination. | | `offset=10` |
| `limit` | number | no | Maximum number of test cases to return (0–5000). May be `0` to return only the total count (no rows). | | `limit=10` |
| `page` | number | no | **Deprecated** — use `offset` instead. 1-based page number. Ignored when `offset` is set. If `limit` is omitted, a default of 10 is applied. | | `page=1` |
| `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` |
| `requirementIds` | string | yes | Filter test cases by requirement ID | | `requirementIds=1CEPaUhuR_abc123def456` |
| `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`, `requirements`, `customFields`, `filterableCustomFields`, `parameterValues` | `include=steps` |
* 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
```bash
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"
```bash
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"
```bash
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
```bash
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
```
#### Skip the first 90 test cases and return the next 15 — or, return 15 rows starting from 0-based index 90
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?offset=90&limit=15&sortField=pos&sortOrder=asc
```
#### Fetch all draft test cases
```bash
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
```bash
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
```bash
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
```bash
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'
```bash
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
```
#### Fetch test cases linked to a specific requirement
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?requirementIds=1CEPaUhuR_abc123def456
```
#### Fetch test cases linked to multiple requirements (OR logic)
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
"https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?requirementIds=1CEPaUhuR_abc123def456&requirementIds=1CEPaUhuR_xyz789ghi012"
```
### Response Fields
```typescript
{
total: number, // Total number of filtered test cases
offset?: number, // The offset that was applied (present when pagination was applied)
limit?: number, // The limit that was applied (present when pagination was applied)
page?: number, // **Deprecated**. Echo of the page that was requested (present only if `page` was used 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: html // Test case precondition text. DEPRECATED, usable but prefer precondition object below
precondition: {
projectId: string, // Project id the precondition belongs to. Same as test cases'
id: number, // Id of the precondition. Not useful unless the precondition is shared
version: number, // Version of the precondition
title?: string, // Title of the precondition. Only populated for shared
type: 'standalone' | 'shared', // Type of the precondition
text: html, // Actual text contents of the precondition
isLatest: boolean, // Whether precondition's version is latest or not
createdAt: string,
updatedAt: string,
deletedAt?: string,
}
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
isEmpty: boolean // Whether the test case is empty (has no comment and steps)
templateTCaseId?: string // Corresponding template test case ID, if it is a filled test case
numFilledTCases? number // Number of corresponding filled test cases, if it is a template 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]: { // Key-value pairs of custom field system names and corresponding details for the test case
value: string // Current value
isDefault: boolean // Whether default value is set by the system or selected by the user
}
}
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
id: number // Unique identifier of the step
type: string // Type of the step (standalone | shared)
version: number // Version of the step (always 1 for standalone steps)
isLatest: boolean // Whether this is the latest version of the step (always true for standalone steps)
title?: string // Title of the step (only for shared steps)
subSteps?: Array<{ // List of sub steps (only for shared steps)
id: number // Unique identifier of the step
type: string // Type of the step (shared_sub_step)
version: number // Version of the step (same as parent step)
isLatest: boolean // Whether this is the latest version (same as parent step)
description: html // Details of the sub step
expected: html // Expected result from the sub step
data?: Array // Sub step test data items (see Step Test Data)
deletedAt?: string // Date the sub step was deleted on
}>
description?: html // Details of step (only for standalone steps)
expected?: html // Expected result from the step (only for standalone steps)
data?: Array // Step test data items, only for standalone steps (see Step Test Data)
deletedAt?: string // Date the step was deleted on
}>
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
}>
parameterValues: { // The details of corresponding filled tcases (relevant only for template tcases)
tcaseId: string // ID of the filled tcase
tcaseVersion: number // 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: html // 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: html // 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: html // 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
```json
{
"total": 4,
"offset": 1,
"limit": 2,
"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": "The \"About Us\" page is opened
",
"precondition": {
"projectId": "2HKj57k3z_YXYQVTdnPqrs8",
"id": 2,
"version": 3,
"type": "standalone",
"text": "The \"About Us\" page is opened
",
"isLatest": true,
"createdAt": "2025-03-25T10:48:34.66935+02:00",
"updatedAt": "2025-03-25T10:48:34.66935+02:00"
},
"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,
"isEmpty": false,
"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": "The \"Checkout\" page is opened
There are pizzas, drinks and desserts
// Sub step test data items (see Step Test Data)
deletedAt?: string // Date the sub step was deleted on
}>
description?: html // Details of step (only for standalone steps)
expected?: html // Expected result from the step (only for standalone steps)
data?: Array // Step test data items, only for standalone steps (see Step Test Data)
deletedAt?: string // Date the step was deleted on
}>
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]: { // Key-value pairs of custom field system names and corresponding details for the test case
value: string // Current value
isDefault: boolean // Whether default value is set by the system or selected by the user
}
}
parameterValues: { // The details of corresponding filled tcases (relevant only for template tcases)
tcaseId: string // ID of the filled tcase
tcaseVersion: number // 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
isEmpty: boolean // Whether the test case is empty (has no comment and steps)
templateTCaseId?: string // Corresponding template test case ID, if it is a filled test case
numFilledTCases? number // Number of corresponding filled test cases, if it is a template test case
createdAt: string // Test case creation time (ISO 8601 format)
updatedAt: string // Test case updation time (ISO 8601 format)
}
```
### Sample Response
```json
{
"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": "The \"About Us\" page is opened
",
"precondition": {
"projectId": "2HKj57k3z_YXYQVTdnPqrs8",
"id": 2,
"version": 3,
"type": "standalone",
"text": "The \"About Us\" page is opened
",
"isLatest": true,
"createdAt": "2025-03-25T10:48:14.243475+02:00",
"updatedAt": "2025-03-25T10:48:14.243475+02:00"
},
"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": [
{
"id": 1,
"type": "standalone",
"version": 1,
"isLatest": true,
"description": "Automated validation of About Us content
",
"expected": "Content matches expected About Us information
"
},
{
"id": 2,
"type": "shared",
"version": 3,
"isLatest": true,
"title": "About us validations",
"subSteps": [
{
"id": 3,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Verify company name and logo are displayed correctly
",
"expected": "Company name and logo match branding guidelines
"
},
{
"id": 4,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Check mission statement content
",
"expected": "Mission statement matches approved text
"
},
{
"id": 5,
"type": "shared_sub_step",
"version": 3,
"isLatest": true,
"description": "Validate team member information
",
"expected": "Team member profiles are accurate and complete
"
}
]
}
],
"customFields": {
"automation": {
"value": "Automated",
"isDefault": false
},
"known_issue": {
"value": "No",
"isDefault": true
}
},
"isDraft": false,
"isLatestVersion": true,
"isEmpty": false,
"createdAt": "2025-03-25T10:48:14.243475+02:00",
"updatedAt": "2025-03-25T10:48:14.243475+02:00"
}
```
## Get Test Case Edit History
`GET /api/public/v0/project/{project_id}/tcase/{tcase_or_legacy_id}/history`
Retrieves the edit history of a single test case — who changed what and when. This is the same data shown in the "Edit History" panel in the web interface. Entries are returned newest first, and history is available even for deleted 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)
### Query Parameters
All query parameters are optional.
| Parameter | Type | Description | Example |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `offset` | number | Number of rows to skip before returning results. Combine with `limit` for offset-based pagination. | `offset=10` |
| `limit` | number | Maximum number of entries to return (0–5000). May be `0` to return only the total count (no rows). | `limit=10` |
| `page` | number | **Deprecated** — use `offset` instead. 1-based page number. Ignored when `offset` is set. If `limit` is omitted, a default of 10 is applied. | `page=1` |
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/55/history
```
### Response Fields
```typescript
{
total: number // Total number of edit history entries for the test case
offset?: number // Offset applied to the query, if any
limit?: number // Limit applied to the query, if any
page?: number // Echoes the deprecated page param when it was used
data: Array<{ // Edit history entries, newest first
id: number // Unique identifier of the entry
actionType: string // What changed (`create` | `change_type` | `delete` | `restore` | `title` | `priority` | `precondition` | `tags` | `steps` | `publish` | `others` | `version_rollback`)
tcaseId: string // Identifier of the test case
authorId: number // Unique identifier of the user who made the change
author: { // Details of the user who made the change
id: number // Unique identifier of the user
name: string // Name of the user
email: string // Email of the user
avatar?: string // Avatar URL of the user; fetching it requires authentication
role: string // Role of the user (`owner` | `admin` | `user` | `test-runner` | `viewer`)
}
oldValue?: string // Value before the change. Populated for `title`, `priority` and `change_type` changes; contains the version number for `version_rollback`
newValue?: string // Value after the change. Populated for the same action types as oldValue
tcaseVersion: number // Version of the test case this change produced
createdAt: string // Time of the change (ISO 8601 format)
}>
}
```
### Sample Response
```json
{
"total": 2,
"data": [
{
"id": 2,
"actionType": "title",
"tcaseId": "1CJg36j1c_yFYPRcmZaoqp3",
"authorId": 1,
"author": {
"id": 1,
"email": "jane@example.com",
"name": "Jane Doe",
"avatar": null,
"role": "admin"
},
"newValue": "User can log in with valid credentials",
"oldValue": "User can log in",
"tcaseVersion": 2,
"createdAt": "2026-08-05T10:48:34.66935+02:00"
},
{
"id": 1,
"actionType": "create",
"tcaseId": "1CJg36j1c_yFYPRcmZaoqp3",
"authorId": 1,
"author": {
"id": 1,
"email": "jane@example.com",
"name": "Jane Doe",
"avatar": null,
"role": "admin"
},
"newValue": null,
"oldValue": null,
"tcaseVersion": 1,
"createdAt": "2026-08-05T10:12: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
```bash
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
1. **Folder-based counting**:
```bash
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"
```
2. **Priority-based counting**:
```bash
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"
```
3. **Tag-based counting**:
```bash
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"
```
4. **Draft status counting**:
```bash
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"
```
5. **Custom field counting**:
```bash
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
```typescript
{
count: number // Total number of test cases matching the filters
}
```
### Example Response
```json
{
"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
## Create Test Case
`POST /api/public/v0/project/{project_id}/tcase`
Creates a new test case in the specified project. You can create both standalone and template test cases using this endpoint.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Request Body
```typescript
{
title: string // Required: Test case title (must be between 1-511 characters)
type: string // Required: Type of test case (`standalone` | `template`)
folderId: number // Required: ID of the folder where the test case will be placed
priority: string // Required: Test case priority (`high` | `medium` | `low`)
pos?: number // Optional: Position within the folder (0-based index)
comment?: html // Optional: Test case precondition. DEPRECATED, if precondition object is empty, comment is used to populated precondition.text
precondition?: // Optional: Test case precondition
| { sharedPreconditionId: number } // Use a shared precondition by specifying its unique id
| { text: html } // Or, use a standalone precondition with text
steps?: Array<{ // Optional: List of test case steps
// For shared steps
sharedStepId?: number // Unique identifier of the shared step
// For standalone steps
description?: html // Details of steps
expected?: html // Expected result from the step
data?: Array // Step test data items, max 20 (see Step Test Data)
}>
tags?: string[] // Optional: List of tag titles (max 255 characters each)
requirements?: Array<{ // Optional: Test case requirement
text: string // Required: Title of the requirement (must be between 1-255 characters)
url: string // Required: URL of the requirement (must be between 1-255 characters)
}>
files?: Array<{ // Optional: Files attached to the test case
id: string // Required: File identifier, typically returned by the upload file endpoint
fileName: string // Required: Original file name
mimeType: string // Required: MIME type of the file
size: number // Required: File size in bytes
url?: string // Optional: File URL returned by the upload file endpoint
}>
links?: Array<{ // Optional: Additional links relevant to the test case
text: string // Required: Title of the link (must be between 1-255 characters)
url: string // Required: URL of the link (must be between 1-255 characters)
}>
customFields?: { // Optional: Custom field values.
[key: string]: { // Custom field system names should be specified as keys. Only custom fields applied and enabled for a project should be specified
isDefault: boolean // Whether to set the default value. Should be true only if the custom field actually has a default value
value: string // Custom field value to be set. Should be specified only if not setting to the default value
}
}
parameterValues?: Array<{ // Optional: Values to substitute for parameters in the filled test cases (only relevant for template types)
values: { // Values for the parameters in the template test case to be substituted for this filled test case
[key: string]: string
}
}>
filledTCaseTitleSuffixParams?: string[] // Optional: Parameters to append to filled test case titles
isDraft?: boolean // Whether to create as draft, default false
}
```
* **Required fields**: `type`, `folderId`, `title`, `priority`
* **Test case types**: Only `standalone` and `template` can be created directly. `filled` test cases are automatically generated from template test cases.
* **Steps**: You can use either shared steps (by `sharedStepId`) or standalone steps (with `description`, `expected`, and/or `data`).
* **Step test data**: Standalone steps can include up to 20 `data` items (see Step Test Data). A step that references a shared step by `sharedStepId` must not include `data`.
* **Custom fields**: Must be created through the web UI before you can set their values via API.
* **Template test cases**: Use `parameterValues` to define parameter substitutions that will generate filled test cases.
* **Parameter names**: The keys of `parameterValues[].values` and the entries of `filledTCaseTitleSuffixParams` must start with a letter, contain only letters, digits, hyphens and underscores, end with a letter or digit, and be at most 255 characters. Placeholders inside the title, precondition and steps are not restricted this way - a `${...}` placeholder whose name breaks these rules is kept as literal text.
* **Position**: If `pos` is not specified, the test case will be added at the end of the folder.
* **Files**: Use the upload file endpoint first. Public upload responses include `id` and `url`; when attaching files to a test case, also provide the matching `fileName`, `mimeType`, and `size`.
### Example Requests
#### Create a Simple Standalone Test Case
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"type": "standalone",
"folderId": 26,
"title": "User should be able to login with valid credentials",
"priority": "high",
"precondition": {
"text": "User has valid account credentials
"
},
"isDraft": false,
"steps": [
{
"description": "Navigate to login page
",
"expected": "Login form is displayed
"
},
{
"description": "Enter valid username and password
",
"expected": "Credentials are accepted
",
"data": [
{
"type": "text",
"label": "Credentials",
"data": { "value": "user@example.com / s3cret", "format": "plaintext" }
},
{
"type": "link",
"label": "Test accounts",
"data": { "value": "https://example.com/wiki/test-accounts" }
}
]
},
{
"description": "Click login button
",
"expected": "User is redirected to dashboard
"
}
],
"tags": ["authentication", "login"],
"requirements": [
{
"text": "REQ-001: User Authentication",
"url": "https://docs.example.com/requirements/auth"
}
]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase
```
#### Create a Template Test Case with Parameters
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"type": "template",
"folderId": 26,
"title": "User should be able to login with ${browser} browser on ${device}",
"priority": "medium",
"precondition": {
"text": "Testing login functionality across different browsers and devices
"
},
"isDraft": false,
"steps": [
{
"description": "Open ${browser} browser on ${device}
",
"expected": "Browser opens successfully
"
},
{
"description": "Navigate to login page
",
"expected": "Login form is displayed correctly
"
},
{
"description": "Enter valid credentials and submit
",
"expected": "Login is successful on ${device}
"
}
],
"tags": ["authentication", "cross-browser", "responsive"],
"parameterValues": [
{
"values": {
"browser": "Chrome",
"device": "Desktop"
}
},
{
"values": {
"browser": "Firefox",
"device": "Desktop"
}
},
{
"values": {
"browser": "Safari",
"device": "Mobile"
}
}
],
"filledTCaseTitleSuffixParams": ["browser", "device"]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase
```
#### Create Test Case with Custom Fields
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"type": "standalone",
"folderId": 26,
"title": "API endpoint validation test",
"priority": "high",
"precondition": {
"text": "Test API endpoint response and data validation
"
},
"isDraft": false,
"steps": [
{
"description": "Send GET request to /api/users endpoint
",
"expected": "Response status is 200
"
},
{
"description": "Validate response JSON structure
",
"expected": "All required fields are present
"
}
],
"customFields": {
"automation": {
"value": "Automated"
},
"test_type": {
"value": "API"
}
},
"tags": ["api", "validation"]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase
```
#### Create Draft Test Case
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"type": "standalone",
"folderId": 26,
"title": "Work in progress test case",
"priority": "low",
"precondition": {
"text": "This test case is still being developed
"
},
"isDraft": true,
"steps": [
{
"description": "Step 1 - to be defined
",
"expected": "Expected result - to be defined
"
}
]
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase
```
### Response Fields
```typescript
{
id: string // Unique identifier of the created test case
seq: number // Sequence number of the test case in the project
}
```
### Example Response
Status: 201 Created
```json
{
"id": "1CJg36j1c_yFYPRcmZaoqp3",
"seq": 57
}
```
### Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------- |
| 400 | Invalid request data or validation errors |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 404 | Project or folder not found |
| 409 | Position conflict or duplicate requirement |
| 500 | Internal server error while creating test case |
**Template Test Cases**
* Template test cases use `${parameter}` syntax in titles, comments, and steps
* Parameter values are substituted when creating filled test cases
* Multiple parameter value sets create multiple filled test cases
* Filled test cases inherit all properties from their template parent
* Updates to template test cases automatically update corresponding filled test cases
## 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
```typescript
{
title?: string // Optional: Test case title (must be between 1-511 characters)
priority?: string // Optional: Test case priority (`high` | `medium` | `low`)
comment?: html // Optional: Test case precondition. DEPRECATED, if precondition object is not present but comment is, value of comment will be used to populated precondition.text
precondition?: // Optional: Test case precondition
| { sharedPreconditionId: number } // Use a shared precondition by specifying its unique id
| { text: html } // Or, use a standalone precondition with text
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
// For shared steps
sharedStepId?: number // Unique identifier of the shared step
// For standalone steps
description?: html // Details of steps
expected?: html // Expected result from the step
data?: Array // Step test data items, max 20 (see Step Test Data)
}>
tags?: string[] // Optional: List of test case tags (title)
requirements?: Array<{ // Optional: Test case requirement
text: string // Title of the requirement (must be between 1-255 characters)
url: string // URL of the requirement (must be between 1-255 characters)
}>
files?: Array<{ // Optional: Files attached to the test case
id: string // File identifier, typically returned by the upload file endpoint
fileName: string // Original file name
mimeType: string // MIME type of the file
size: number // File size in bytes
url?: string // File URL returned by the upload file endpoint
}>
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?: { // Optional: Custom field values to update. Only specified custom fields are updated, others are left as is
[key: string]: { // Custom field system names should be specified as keys. Only custom fields applied and enabled for a project should be specified
isDefault: boolean // Whether to set the default value. Should be true only if the custom field actually has a default value
value: string // Custom field value to be set. Should be specified only if not setting to the default value
}
}
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
}
}>
}
```
* All top-level fields are optional. Include only the top-level fields that need to be updated in the request.
* For `customFields`, only the specified `key` values are updated; others remain unchanged.
* Steps can be either `shared` or `standalone`. To use a shared step, specify `sharedStepId`. For standalone steps, specify `description`, `expected`, and/or `data`.
* Standalone steps can include up to 20 `data` items (see Step Test Data). If you update `steps`, send the complete step list including each step's `data` — sending a step with an empty or omitted `data` list removes all its test data, and a step whose only content was `data` is dropped from the test case entirely. A step that references a shared step by `sharedStepId` must not include `data`.
* Filled test case type cannot be updated.
* If you update `files`, send the complete list of files you want stored on the test case.
* The keys of `parameterValues[].values` and the entries of `filledTCaseTitleSuffixParams` must follow the parameter name rules described under the create endpoint.
### Example Request
#### Switch to a Shared Precondition, Updating Test Case Title, Priority And Custom Field Value
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"title": "Changing to corresponding cursor after hovering the element",
"precondition": {
"id": 42
},
"priority": "high",
"customFields": {
"automation": {
"isDefault": false,
"value": "Automated"
}
}
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/1
```
#### Updating Multiple Custom Fields Values
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-H "Content-Type: application/json" \
-d '{
"customFields": {
"automation": {
"isDefault": false,
"value": "Cannot be Automated"
},
"known_issue": {
"isDefault": true
}
}
}' \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase/56
```
* Custom fields and shared steps 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
```json
{
"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 |
---
# Custom Fields
URL: /docs/api/tcases_custom_fields
Custom fields allow you to extend test cases with additional metadata specific to your organization's needs. You can use custom fields to track information like automation status, test environment, component ownership, or any other project-specific attributes.
## Types of Custom Fields
In QA Sphere, there are four types of custom fields:
1. **Text**: A plain string value.
2. **Rich Text**: Text supporting formatting, held as HTML (see [HTML Support](https://qasphere.com/docs/api/html-support)).
3. **Dropdown**: One value out of the field's list of options.
4. **Checkbox**: A boolean.
* **Single option checkbox**: the option holds the label of the checked value, and an unchecked field holds an empty value.
* **Two option checkbox**: option order is significant, the first option holds the label of the checked value and the second one that of the unchecked value. The field always holds one of the two.
Every custom field has a display `name` and a `systemName`. The display name can be changed at any time, the system name cannot.
Keep system names short and readable, such as `automation` or `test_environment`, since they appear in test case payloads and filters and cannot be changed later.
A field can be marked `required` and can carry a `defaultValue`, which is applied to test cases that do not provide a value of their own. A required field always has a default value. For a checkbox, both follow from its options instead of being configurable:
* **Single option checkbox**: never required and has no default value.
* **Two option checkbox**: always required, with its unchecked value as the default value.
Only fields with `enabled: true` are meant to be used, and a field applies either to all projects (`allowAllProjects: true`) or only to the projects listed in `allowedProjectIds`.
## Using Custom Fields in Test Cases
Custom fields can be used when creating or updating test cases. Values are keyed by the field's `systemName`, not by its `id`.
### Creating Test Cases with Custom Fields
When creating a test case, you can include custom field values using the `customFields` object:
```json
{
"type": "standalone",
"folderId": 1,
"title": "Login Test",
"priority": "high",
"customFields": {
"automation": {
"value": "Automated"
},
"test_environment": {
"value": "production"
},
"regression": {
"value": "Yes"
},
"notes": {
"value": "Covers the happy path only.
"
}
}
}
```
### Custom Field Value Structure
Each custom field value in the `customFields` object should have:
* `value`: The actual value for the field. For dropdown and checkbox fields it must match one of the option `value` strings from the field's `options` array. An empty value is accepted only by a field that is not required, which is why a single option checkbox always takes one and a two option checkbox never does. Richtext values are HTML and are sanitized server-side
* `isDefault`: Boolean indicating whether to use the field's default value. When `true`, `value` must either be left out or match the field's default value, and the field must have a default value at all
### Using Default Values
You can use the default value for a custom field by setting `isDefault: true`, leaving out `value` or setting it to the field's default value:
```json
{
"customFields": {
"automation": {
"isDefault": true
}
}
}
```
The flag ties the test case value to the field definition. Whenever the field's `defaultValue` changes afterwards, the new default is applied to every test case value carrying `isDefault: true` and to every test case that has no value for the field, while clearing the field's default value removes those values again.
Default values are also applied without the flag:
* In a create request, a field left out of `customFields` takes the field's default value, if it has one, and is marked with `isDefault: true`. A required field does the same when an empty value is passed, while for a field that is not required an empty value is stored as an empty value.
* In an update request, only the fields present in `customFields` are changed and no default value is filled in. A required field can therefore not be given an empty value, unless `isDefault` is set.
### Filtering Test Cases by Custom Fields
Custom fields can also be used to filter test cases when listing them. Use the format `cf_{systemName}=value` in query parameters:
```bash
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"
```
Multiple values for the same custom field can be specified:
```bash
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&cf_automation=In%20Progress"
```
## List Project Custom Fields
`GET /api/public/v0/project/{project_id}/custom-field`
Returns all custom fields available for the project. This endpoint is useful when creating or updating test cases that include custom field values.
### Path Parameters
* `project_id`: The project identifier (can be either the project code or UUID)
### Response
Status: 200 OK
```typescript
{
customFields: Array<{
id: string // Unique custom field identifier
type: 'text' | 'dropdown' | 'checkbox' | 'richtext' // Field type
systemName: string // System identifier for the field (used in API requests)
name: string // Display name of the field
required: boolean // Whether the field is required for test cases
enabled: boolean // Whether the field is currently enabled
options?: Array<{
// Available options, only for dropdown and checkbox fields
id: string // Option identifier
value: string // Option display value
}>
defaultValue?: string // Default value for the field, implied by the options for checkbox fields
pos: number // Display position/order
allowAllProjects: boolean // Whether the field is available to all projects
allowedProjectIds?: string[] // List of project IDs if not available to all projects
createdAt: string // ISO 8601 timestamp when the field was created
updatedAt: string // ISO 8601 timestamp when the field was last updated
}>
}
```
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/custom-field
```
### Example Response
```json
{
"customFields": [
{
"id": "1customfield_1111111111111",
"type": "dropdown",
"systemName": "automation",
"name": "Automation",
"required": false,
"enabled": true,
"options": [
{
"id": "1customfieldoption_1111111111111",
"value": "Planned"
},
{
"id": "1customfieldoption_1111111111112",
"value": "Cannot be Automated"
},
{
"id": "1customfieldoption_1111111111113",
"value": "In Progress"
},
{
"id": "1customfieldoption_1111111111114",
"value": "Automated"
},
{
"id": "1customfieldoption_1111111111115",
"value": "Broken"
}
],
"defaultValue": "Planned",
"pos": 0,
"allowAllProjects": true,
"allowedProjectIds": [],
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
},
{
"id": "1customfield_1111111111112",
"type": "text",
"systemName": "test_environment",
"name": "Test Environment",
"required": true,
"enabled": true,
"options": [],
"defaultValue": "staging",
"pos": 1,
"allowAllProjects": false,
"allowedProjectIds": ["1project_1111111111111"],
"createdAt": "2024-01-20T14:15:00Z",
"updatedAt": "2024-01-20T14:15:00Z"
},
{
"id": "1customfield_1111111111113",
"type": "checkbox",
"systemName": "regression",
"name": "Regression",
"required": true,
"enabled": true,
"options": [
{
"id": "1customfieldoption_1111111111116",
"value": "Yes"
},
{
"id": "1customfieldoption_1111111111117",
"value": "No"
}
],
"defaultValue": "No",
"pos": 2,
"allowAllProjects": true,
"allowedProjectIds": [],
"createdAt": "2024-02-01T09:00:00Z",
"updatedAt": "2024-02-01T09:00:00Z"
},
{
"id": "1customfield_1111111111114",
"type": "richtext",
"systemName": "notes",
"name": "Notes",
"required": false,
"enabled": true,
"options": [],
"pos": 3,
"allowAllProjects": true,
"allowedProjectIds": [],
"createdAt": "2024-02-05T11:45:00Z",
"updatedAt": "2024-02-05T11:45:00Z"
}
]
}
```
### Error Responses
| Status Code | Description |
| ----------- | -------------------------------------------- |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 404 | Project not found |
| 500 | Internal server error |
## Related Resources
* [Test Cases](https://qasphere.com/docs/api/tcases) - Create and manage test cases with custom fields
* [Authentication](https://qasphere.com/docs/api/authentication) - Learn about API authentication
---
# Upload Files
URL: /docs/api/upload_file
The upload file endpoints allow you to upload files to QA Sphere.
Uploaded files can be referenced in the `files` field of public test case create/update requests and inside HTML fields. Public result endpoints currently support links only and do not accept file attachments.
## Upload File
`POST /api/public/v0/file`
Upload a file to QA Sphere.
### Request Body
Request body should be a `multipart/form-data` with a `file` form-field.
### Limits
* Maximum file size: `50 MiB`
### Response Fields
| Field | Type | Description |
| ----------- | -------- | -------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier for the uploaded file |
| `stableUrl` | `string` | Host-relative URL of the uploaded file; safe across subdomain changes (use this) |
| `url` | `string` | Absolute URL of the uploaded file |
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-F 'file=@"/path/to/file"' \
https://your-company.your-region-code.qasphere.com/api/public/v0/file
```
### Example Response
```json
{
"id": "1CJLabPkq_PWeS4siaKcB1k",
"stableUrl": "/api/file/1CJLabPkq_PWeS4siaKcB1k",
"url": "https://your-company.your-region-code.qasphere.com/api/file/1CJLabPkq_PWeS4siaKcB1k"
}
```
### Error Responses
| Status Code | Description |
| ----------- | -------------------------------------------- |
| 400 | Invalid multipart request or missing `file` |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 413 | File exceeds the `50 MiB` limit |
| 500 | Internal server error while uploading file |
## Upload Files In Batch
`POST /api/public/v0/file/batch`
Upload multiple files to QA Sphere in a single request.
### Request Body
Request body should be a `multipart/form-data` with one or more `files` form-fields.
### Limits
* Maximum files per request: `100`
* Maximum file size: `50 MiB` per file
* Maximum request body size: `500 MiB`
### Response Fields
```typescript
{
files: Array<{
id: string // Unique identifier for the uploaded file
stableUrl: string // Host-relative URL; safe across subdomain changes (use this)
url: string // Absolute URL
}>
}
```
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
-F 'files=@"/path/to/file1"' \
-F 'files=@"/path/to/file2"' \
https://your-company.your-region-code.qasphere.com/api/public/v0/file/batch
```
### Example Response
```json
{
"files": [
{
"id": "1CJLabPkq_PWeS4siaKcB1k",
"stableUrl": "/api/file/1CJLabPkq_PWeS4siaKcB1k",
"url": "https://your-company.your-region-code.qasphere.com/api/file/1CJLabPkq_PWeS4siaKcB1k"
},
{
"id": "1CJLabPkq_Q2x7A7Lwu7GsL5",
"stableUrl": "/api/file/1CJLabPkq_Q2x7A7Lwu7GsL5",
"url": "https://your-company.your-region-code.qasphere.com/api/file/1CJLabPkq_Q2x7A7Lwu7GsL5"
}
]
}
```
### Error Responses
| Status Code | Description |
| ----------- | --------------------------------------------------------------- |
| 400 | Invalid multipart request, no files provided, or too many files |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 413 | A file exceeds `50 MiB` or request body exceeds `500 MiB` |
| 500 | Internal server error while uploading files |
\:::tip Use `stableUrl`
Prefer the `stableUrl` field when referencing an uploaded file. It is host-relative (e.g. `/api/file/{id}`) and keeps resolving even after your tenant's subdomain changes. URLs that embed the old subdomain stop working once the subdomain changes.
\:::
\:::note Relative file URLs in responses
Read endpoints (e.g. `GET /tcase/{id}`, `GET /run/{id}`) return file references **embedded in HTML fields**, such as `precondition.text`, `steps[].description`, `steps[].expected`, run/plan descriptions, and comments, as host-relative URLs (`/api/file/{id}`). To fetch such an attachment, prepend your tenant base URL (e.g. `https://your-company.your-region-code.qasphere.com`). The dedicated `files[].url` field on the test-case response remains absolute.
\:::
---
# Users
URL: /docs/api/users
The users endpoint allows administrators to retrieve information about all users in the system.
## List Users
`GET /api/public/v0/users`
Returns a list of all users in the system. This endpoint is restricted to administrators only.
### Authentication
Requires an API key with Admin role permissions. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Response Format
```typescript
{
users: Array<{
email: string // User's email address
name: string // User's display name
role: string // User's role ('owner' | 'admin' | 'user' | 'test-runner' | 'viewer')
authorizationTypes: Array<'password' | 'google'> // Authentication methods
totpEnabled: boolean // Two-factor authentication status
createdAt: string // ISO 8601 timestamp
lastActivity: string // ISO 8601 date
}>
}
```
### User Roles
| Role | Permissions |
| --------------- | ----------------------------------------- |
| **Owner** | Full system access with tenant management |
| **Admin** | Full project access with user management |
| **User** | Can create and manage test cases and runs |
| **Test Runner** | Can execute test runs only |
| **Viewer** | Read-only access to projects |
### Example Request
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/users
```
### Example Response
```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"
}
]
}
```
### Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------- |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions (non-admin access) |
| 500 | Internal server error |
### Important Notes
| Requirement | Description |
| ----------- | -------------------------------------------------- |
| Email | Must be valid and unique within the system |
| User names | Must be between 1 and 255 characters |
| Dates | Creation and activity dates are in ISO 8601 format |
| Access | Only administrators can access this endpoint |
This endpoint enables you to:
* Audit user access and roles
* Monitor user activity
* Verify authentication methods
* Check 2FA adoption
## Get Current User
`GET /api/public/v0/users/me`
Returns the user identity associated with the calling credential — the API key creator, or the user who consented to an OAuth authorization. Available to any authenticated role.
### Authentication
Requires either an API key or an OAuth Bearer token. See [Authentication](https://qasphere.com/docs/api/authentication) for more details.
### Response Format
```typescript
{
user: {
id: number // User's numeric ID
email: string // User's email address
name: string // User's display name
avatar: string | null // Avatar URL, if set; fetching it requires authentication
role: 'owner' | 'admin' | 'user' | 'test-runner' | 'viewer'
}
}
```
### Example Request (API Key)
```bash
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/users/me
```
### Example Request (OAuth Bearer)
```bash
curl \
-H "Authorization: Bearer your-oauth-access-token" \
https://your-company.your-region-code.qasphere.com/api/public/v0/users/me
```
### Example Response
```json
{
"user": {
"id": 42,
"email": "you@example.com",
"name": "Your Name",
"avatar": null,
"role": "admin"
}
}
```
### Error Responses
| Status Code | Description |
| ----------- | ----------------------------- |
| 401 | Invalid or missing credential |
| 500 | Internal server error |
---
# ClickUp
URL: /docs/clickup
QA Sphere allows you to integrate with ClickUp using the Custom Issue Tracker feature. This integration enables you to create ClickUp tasks directly while going through test cases in a test run, streamlining your workflow and ensuring efficient issue tracking within your ClickUp workspace.
## Configuring ClickUp as a Custom Issue Tracker
To integrate ClickUp into QA Sphere, follow these steps:
1. Go to **Settings** by clicking the gear icon
qasphere playwright-json-upload [options]
qasphere allure-upload [options]
```
All three match test results to existing QA Sphere test cases using markers in the test name (or framework-specific annotations) and upload them as a new or existing test run.
For language- and framework-specific setup, see the per-framework guides:
* [Playwright Integration](https://qasphere.com/docs/cli-usage-playwright)
* [Cypress Integration](https://qasphere.com/docs/cli-usage-cypress)
* [Python / pytest Integration](https://qasphere.com/docs/cli-usage-pytest)
* [WebdriverIO Integration](https://qasphere.com/docs/cli-usage-webdriverio)
* [Auto-create test cases with Playwright](https://qasphere.com/docs/integrations/result-upload/playwright-create-tcases-guide)
## Supported report formats and framework coverage
The CLI is **language- and framework-agnostic**. It speaks three report formats, with JUnit XML acting as the universal lingua franca:
* **JUnit XML** (`junit-upload`) — supported by virtually every test framework across every language. If your tool can produce JUnit-style XML, the CLI can upload it.
* **Playwright JSON** (`playwright-json-upload`) — Playwright's native JSON report. Adds support for test annotations as a more reliable matching method than markers in test names.
* **Allure** (`allure-upload`) — Allure results directories (`*-result.json`). Adds TMS link matching for test case linking.
The CLI itself ships as an npm package, but it does **not** require your project to be JavaScript:
| Language | Frameworks / tools |
| --------------------------- | ----------------------------------------------------- |
| **JavaScript / TypeScript** | Playwright, Cypress, Jest, Mocha, WebdriverIO, Vitest |
| **Python** | pytest, unittest, Robot Framework |
| **Java / Kotlin** | JUnit 4/5, TestNG, Selenium, Appium |
| **Go** | `go test` (with `-v` and `go-junit-report`) |
| **C# / .NET** | NUnit, xUnit, MSTest |
| **Rust** | `cargo test` (with `cargo2junit`) |
| **Ruby** | RSpec, Minitest |
| **PHP** | PHPUnit |
If your stack isn't listed but can emit JUnit XML, Playwright JSON, or Allure results, it works.
## Upload modes
Each command supports two modes:
* **Upload into an existing run** — pass `-r, --run-url ` pointing at a QA Sphere run. The project code and run ID are extracted from the URL.
* **Create a new run** — omit `--run-url`. Use `--project-code`, `--run-name`, and `--create-tcases` to control how the run is created.
```bash
# Upload into an existing run
qasphere junit-upload -r https://qas.eu1.qasphere.com/project/PRJ/run/23 ./test-results.xml
# Create a new run automatically
qasphere junit-upload ./test-results.xml
# Create a new run with explicit project and run name
qasphere junit-upload --project-code PRJ --run-name "v1.4.4-rc5" ./test-results.xml
```
## Options
All three upload commands share the same option surface.
| Option | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-r, --run-url ` | URL of an existing test run to upload into. Project code and run ID are extracted from the URL. |
| `--project-code ` | Project code for creating a new run (when `--run-url` is not set). Can be auto-detected from markers, but explicit is recommended. |
| `--run-name ` | Name template for the new test run. Supports `{env:VAR}` and date placeholders. Default: `"Automated test run - {MMM} {DD}, {YYYY}, {hh}:{mm}:{ss} {AMPM}"` |
| `--create-tcases` | Create new test cases in QA Sphere for results that have no valid marker. Generates a mapping file (`qasphere-automapping-YYYYMMDD-HHmmss.txt`). Only applies when creating a new run. |
| `--attachments` | Detect and upload file attachments (screenshots, videos, traces) alongside each result. |
| `--force` | Ignore API request errors, invalid test case mappings, or attachment problems and continue uploading. |
| `--ignore-unmatched` | Suppress individual unmatched-test messages; show a summary count only. |
| `--skip-report-stdout ` | When to skip stdout from test results. Choices: `on-success`, `never` (default). |
| `--skip-report-stderr ` | When to skip stderr from test results. Choices: `on-success`, `never` (default). |
| `--verbose` | Show full stack traces on errors. |
| `-h, --help` | Show command help. |
## Run-name template placeholders
The `--run-name` option supports the following placeholders. It is only honored when creating a new run (i.e. when `--run-url` is not set).
| Placeholder | Description |
| ---------------- | ---------------------------- |
| `{env:VAR_NAME}` | Environment variable value |
| `{YYYY}`, `{YY}` | 4-digit / 2-digit year |
| `{MMM}` | 3-letter month (Jan, Feb, …) |
| `{MM}` | 2-digit month |
| `{DD}` | 2-digit day |
| `{HH}` | 2-digit hour, 24-hour format |
| `{hh}` | 2-digit hour, 12-hour format |
| `{mm}`, `{ss}` | Minutes / seconds |
| `{AMPM}` | AM/PM indicator |
Example:
```bash
qasphere junit-upload \
--project-code PRJ \
--run-name "CI Build {env:BUILD_NUMBER} - {YYYY}-{MM}-{DD}" \
./test-results.xml
```
With `BUILD_NUMBER=v1.4.4-rc5` on 2026-01-01, this produces a run named `CI Build v1.4.4-rc5 - 2026-01-01`.
## Test case matching
Results are linked to QA Sphere test cases via markers. The CLI checks them in the order shown below and falls back to the next format if a result doesn't match.
### JUnit XML
JUnit XML supports three marker styles, checked in order:
1. **Hyphenated marker (all languages):** `PROJECT-SEQUENCE` anywhere in the test name. `PROJECT` is your project code; `SEQUENCE` is the test case number (minimum 3 digits, zero-padded if needed). Matched case-insensitively.
* `PRJ-002: Login with valid credentials`
* `Login with invalid credentials: PRJ-1312`
2. **Underscore-separated hyphenless marker (pytest, Go, Rust, …):** for languages where hyphens aren't allowed in test names. The test name must start with `test` (case-insensitive).
* `test_prj002_login_with_valid_credentials`
* `test_login_with_invalid_credentials_prj1312`
3. **CamelCase hyphenless marker (Go, Java):** detected at the start (after the `Test` prefix) or end of the name. The test name must start with `Test` (case-insensitive).
* `TestPrj002LoginWithValidCredentials`
* `TestLoginWithValidCredentialsPrj1312`
### Playwright JSON
Playwright JSON supports two methods, checked in order:
1. **Test annotations (recommended)** — add a [Playwright test annotation](https://playwright.dev/docs/test-annotations#annotate-tests) with `type: "test case"` (case-insensitive) and the full QA Sphere test case URL as `description`:
```typescript
test(
'user login',
{
annotation: {
type: 'test case',
description: 'https://qas.eu1.qasphere.com/project/PRJ/tcase/123',
},
},
async ({ page }) => {
// test code
}
)
```
2. **Hyphenated marker in the test name** — same `PROJECT-SEQUENCE` format as JUnit. Hyphenless markers are **not** supported for Playwright JSON.
### Allure
Allure results use one `*-result.json` file per test in a results directory. `allure-upload` matches via:
1. **TMS links (recommended)** — `links[]` entries with:
* `type: "tms"`
* `url`: QA Sphere test case URL, e.g. `https://qas.eu1.qasphere.com/project/PRJ/tcase/123`
2. **TMS link name fallback** — if `url` is not a QA Sphere URL, the marker in `links[].name` is used (e.g. `PRJ-123`)
3. **Marker in `name`** — same `PROJECT-SEQUENCE` format as JUnit
Only Allure JSON result files (`*-result.json`) are supported. Legacy Allure 1 XML files are ignored.
If markers are missing, the upload fails by default. Use `--create-tcases` to automatically create test cases in QA Sphere for unmatched results, or `--ignore-unmatched` / `--force` to bypass the mismatch without creating them.
## Run-level logs
The CLI automatically detects global or suite-level failures (typically setup/teardown issues that aren't tied to a specific test case) and uploads them as run-level logs:
* **JUnit XML** — suite-level `` elements and empty-name `` entries with `` or `` (e.g. Maven Surefire's synthetic entries for setup/teardown failures).
* **Playwright JSON** — top-level `errors[]` entries (global setup/teardown failures).
* **Allure** — failed or broken `befores` / `afters` fixtures in `*-container.json` files (e.g. pytest session/module-level setup/teardown failures).
## Common examples
```bash
# Upload with attachments
qasphere junit-upload --attachments ./test1.xml
# Force upload even with missing test cases or attachments
qasphere junit-upload --force ./test-results.xml
# Suppress per-test unmatched messages (gradual test-case linking)
qasphere junit-upload --ignore-unmatched ./test-results.xml
# Skip stdout for passed tests to reduce payload size
qasphere junit-upload --skip-report-stdout on-success ./test-results.xml
# Allure upload into an existing run
qasphere allure-upload -r https://qas.eu1.qasphere.com/project/P1/run/23 ./allure-results
# Continue Allure upload when some *-result.json files are malformed
qasphere allure-upload --force -r https://qas.eu1.qasphere.com/project/P1/run/23 ./allure-results
```
---
# Uploading Playwright Results with Auto Test Case Creation
URL: /docs/integrations/result-upload/playwright-create-tcases-guide
This guide walks through the workflow for a QA engineer who has automated manual test cases from the **Bistro Delivery** project using Playwright and wants to report results back to QA Sphere — including automatically creating test cases in QA Sphere for any Playwright tests that don't yet have a matching case.
VIDEO
***
## When to use `--create-tcases`
By default, `playwright-json-upload` requires every test in the report to reference an existing QA Sphere test case (via an annotation or a `BD-XXX` marker in the test name). If any test lacks a valid reference, the upload fails.
The `--create-tcases` flag changes this behavior: instead of failing, the CLI **creates new test cases** in QA Sphere for any unmatched tests and includes them in the test run. A mapping file is generated so you can update your tests with the assigned codes going forward.
This is useful when:
* You're starting fresh and have Playwright tests that don't reference QA Sphere cases yet
* You've added new tests and want them tracked in QA Sphere without manually creating cases first
***
## Prerequisites
* Node.js 22+
* QAS CLI installed: `npm install -g qas-cli`
* Playwright project with JSON reporter configured
* A QA Sphere account with the **Bistro Delivery** project (project code: `BD`)
* A QA Sphere API token
***
## Step 1: Configure environment
Create a `.qaspherecli` file in your project root (or export as environment variables):
```sh
QAS_TOKEN=your_api_token_here
QAS_URL=https://qas.eu1.qasphere.com
```
***
## Step 2: Configure Playwright JSON reporter
In your `playwright.config.ts`, enable the JSON reporter:
```typescript
import { defineConfig } from '@playwright/test'
export default defineConfig({
reporter: [
['list'],
['json', { outputFile: 'test-results/results.json' }]
],
})
```
***
## Step 3: (Recommended) Add test case annotations
If your Playwright tests already reference QA Sphere test cases, annotate them so the CLI can match them precisely. This is the recommended approach for existing test cases:
```typescript
test(
'Add item to cart',
{
annotation: {
type: 'test case',
description: 'https://qas.eu1.qasphere.com/project/BD/tcase/002',
},
},
async ({ page }) => {
// test code
}
)
```
Alternatively, include the `BD-XXX` marker in the test name:
```typescript
test('BD-002: Add item to cart', async ({ page }) => {
// test code
})
```
Tests **without** an annotation or marker are the ones that will be auto-created when using `--create-tcases`.
***
## Step 4: Run Playwright tests
```bash
npx playwright test
```
This generates `test-results/results.json`.
***
## Step 5: Upload results with `--create-tcases`
```bash
qasphere playwright-json-upload test-results/results.json --project-code BD --create-tcases
```
The CLI will:
1. Create a new test run in the BD project (named automatically, e.g. `Automated test run - Apr 22, 2025, 10:34:00 AM`)
2. Match tests that have valid `BD-XXX` markers or annotations to existing test cases
3. **Create new QA Sphere test cases** for any tests without a valid marker
4. Upload pass/fail status for all tests
Any test cases that were not found in QA Sphere will be automatically created and placed in the **cli-import** folder in your project.
To give the run a meaningful name, add `--run-name`:
```bash
qasphere playwright-json-upload test-results/results.json --project-code BD --run-name "Bistro E2E - {YYYY}-{MM}-{DD}" --create-tcases
```
***
## Step 6: Check the mapping file
After the upload, the CLI generates a mapping file in your working directory, for example:
```
qasphere-automapping-20250422-103400.txt
```
It lists the QA Sphere sequence numbers assigned to each newly created test case:
```
"Verify checkout total" → BD-025
"Validate empty cart message" → BD-026
```
**Update your Playwright tests** to include these markers so future uploads match the existing cases instead of creating duplicates:
```typescript
test('BD-025: Verify checkout total', async ({ page }) => {
// test code
})
```
***
## Quick reference
| Goal | Command |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Upload to a new run, auto-create missing test cases | `qasphere playwright-json-upload results.json --project-code BD --create-tcases` |
| Same, with a custom run name | `qasphere playwright-json-upload results.json --project-code BD --run-name "Sprint 12" --create-tcases` |
| Upload to an existing run (no auto-creation needed) | `qasphere playwright-json-upload results.json -r https://qas.eu1.qasphere.com/project/BD/run/23` |
| Upload with screenshots attached | `qasphere playwright-json-upload results.json --project-code BD --create-tcases --attachments` |
| Suppress unmatched test warnings (without creating cases) | `qasphere playwright-json-upload results.json --project-code BD --ignore-unmatched` |
***
## Notes
* `--create-tcases` only works when **creating a new test run** (i.e., without `--run-url`). It cannot create test cases when uploading to an existing run.
* Run the mapping file update step before your next CI run to avoid creating duplicate test cases.
* If you want to silence unmatched test warnings without auto-creating cases, use `--ignore-unmatched` instead.
---
# Playwright Integration
URL: /docs/cli-usage-playwright
See a working example: [bistro-e2e](https://github.com/Hypersequent/bistro-e2e) — Playwright E2E tests with QA Sphere integration.
# Playwright Integration
This guide covers Playwright-specific setup. For install/auth/upload-command reference, see [Overview](/docs/cli), [Auth](/docs/cli/auth), and [Result Upload](/docs/integrations/result-upload).
The CLI supports **two upload paths** for Playwright:
1. **`playwright-json-upload`** (recommended) — uses Playwright's native JSON report with support for test annotations.
2. **`junit-upload`** — uses Playwright's JUnit reporter output.
## Prerequisites
* QAS CLI installed and authenticated — see the [Overview](/docs/cli).
* Playwright test project.
## Configure a reporter
Pick one of the reporters below depending on which upload path you'll use. JSON is recommended because it supports test annotations.
### Option A: JSON reporter (recommended)
```javascript
// playwright.config.js
const { defineConfig } = require('@playwright/test');
module.exports = defineConfig({
testDir: './tests',
timeout: 30000,
reporter: [
['list'],
['json', { outputFile: 'test-results/results.json' }],
],
use: {
headless: true,
screenshot: 'only-on-failure',
video: 'retain-on-failure',
trace: 'retain-on-failure',
},
projects: [
{ name: 'chromium', use: { browserName: 'chromium' } },
{ name: 'firefox', use: { browserName: 'firefox' } },
{ name: 'webkit', use: { browserName: 'webkit' } },
],
});
```
### Option B: JUnit XML reporter
```javascript
// playwright.config.js
const { defineConfig } = require('@playwright/test');
module.exports = defineConfig({
testDir: './tests',
timeout: 30000,
reporter: [
['list'],
['junit', { outputFile: 'junit-results/results.xml' }],
],
use: {
headless: true,
screenshot: 'only-on-failure',
video: 'retain-on-failure',
trace: 'retain-on-failure',
},
});
```
## Attachments
When you pass `--attachments`, the CLI picks up the three artifact types Playwright produces automatically:
| Artifact | Enabled by |
| --------------- | ------------------------------------------------------------------------- |
| **Screenshots** | `use.screenshot: 'only-on-failure'` (or `'on'`) in `playwright.config.js` |
| **Videos** | `use.video: 'retain-on-failure'` (or `'on'`) |
| **Traces** | `use.trace: 'retain-on-failure'` (or `'on-first-retry'`) |
Each attachment is matched to its test case and uploaded alongside the result. Paths inside the JSON/JUnit report must be resolvable from the working directory the upload command runs in.
## Link tests to QA Sphere test cases
Playwright JSON supports two matching methods, checked in order: test annotations (recommended) and hyphenated `PROJECT-SEQUENCE` markers in the test name. JUnit XML supports the hyphenated marker only (plus the underscore/CamelCase variants — see [Result Upload — Test case matching](/docs/integrations/result-upload#test-case-matching)).
### Test annotations (Playwright JSON only)
Add a [Playwright test annotation](https://playwright.dev/docs/test-annotations#annotate-tests) with `type: "test case"` and the full QA Sphere test case URL:
```typescript
// tests/login.spec.ts
import { test, expect } from '@playwright/test';
test(
'Login with valid credentials',
{
annotation: {
type: 'test case',
description: 'https://qas.eu1.qasphere.com/project/PRJ/tcase/312',
},
},
async ({ page }) => {
await page.goto('https://example.com/login');
// ...
}
);
```
### Hyphenated marker in the test name
Works with both Playwright JSON and JUnit XML:
```typescript
test('PRJ-312: Login with valid credentials', async ({ page }) => {
// ...
});
test('Login with invalid credentials: PRJ-313', async ({ page }) => {
// ...
});
```
For `playwright-json-upload`, only annotations and hyphenated markers are supported. The underscore-separated and CamelCase variants are JUnit-only.
## Upload results
```bash
# Recommended: JSON path
npx playwright test
npx qas-cli playwright-json-upload --attachments test-results/results.json
# JUnit XML path
npx qas-cli junit-upload --attachments junit-results/results.xml
```
A convenient npm script:
```json
{
"scripts": {
"test": "playwright test",
"test:upload": "playwright test && npx qas-cli playwright-json-upload --attachments test-results/results.json"
}
}
```
For the full option reference, run-name templates, and modes (new run vs existing), see [Result Upload](/docs/integrations/result-upload).
---
# Python (pytest) Integration
URL: /docs/cli-usage-pytest
See a working example: [bistro-e2e-python](https://github.com/Hypersequent/bistro-e2e-python) — Playwright for Python (pytest) E2E tests with QA Sphere integration.
# Python (pytest) Integration
This guide covers pytest-specific setup. For install/auth/upload-command reference, see [Overview](/docs/cli), [Auth](/docs/cli/auth), and [Result Upload](/docs/integrations/result-upload).
While the examples below use Playwright for Python, the same approach works with **any Python test framework** that emits JUnit XML — pytest + Selenium, Robot Framework, plain unit tests, and so on.
## Prerequisites
* Python 3.8+ (3.13+ recommended) and a pytest project.
* QAS CLI installed and authenticated — see the [Overview](/docs/cli). The CLI is distributed as an npm package, so Node.js 22+ is required for the CLI itself (not for your Python project).
## Configure JUnit XML output
pytest has built-in JUnit XML support via the `--junitxml` flag. Wire it up in `pyproject.toml` so it runs automatically:
```toml
# pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = [
"--junitxml=junit-results/results.xml",
]
```
Or pass it directly:
```bash
pytest --junitxml=junit-results/results.xml
```
### With Playwright for Python
To also capture screenshots and traces for failures:
```toml
# pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = [
"--screenshot=on",
"--tracing=retain-on-failure",
"--junitxml=junit-results/results.xml",
]
```
## Mark tests with QA Sphere markers
Python function names cannot contain hyphens, so the CLI supports an **underscore-separated hyphenless marker**. The function name must start with `test` (the standard pytest convention); the marker can appear immediately after `test_` or at the end of the name.
Format: `test_PROJECTSEQUENCE_description` — where `PROJECT` is the project code and `SEQUENCE` is the test case number (minimum 3 digits, zero-padded if needed).
```python
# tests/test_ui_cart.py
from playwright.sync_api import Page
def test_bd023_cart_operations(page: Page, demo_base_url: str) -> None:
"""BD-023: User should see product list on the Checkout page."""
page.goto(f"{demo_base_url}/")
page.locator(".menu-item").first.locator(".add-to-cart").click()
page.locator(".cart-btn").click()
assert page.locator(".checkout-items").is_visible()
def test_bd022_order_with_cash_payment(page: Page, demo_base_url: str) -> None:
"""BD-022: User should place the order successfully with Cash payment."""
# ...
```
Valid function names:
* `test_bd023_cart_operations` — marker `bd023` at the start (after `test_`)
* `test_cart_operations_bd023` — marker `bd023` at the end
The underscore marker is matched case-insensitively: `test_bd023_...` and `test_BD023_...` both resolve to `BD-023`.
It's good practice to include the hyphenated form in the docstring for human readability while keeping the underscore marker in the function name for matching.
For all supported marker formats and matching rules, see [Result Upload — Test case matching](/docs/integrations/result-upload#test-case-matching).
## Upload results
```bash
# Run pytest (writes junit-results/results.xml via pyproject.toml)
pytest --browser chromium -v
# Upload
npx qas-cli junit-upload --project-code BD --attachments junit-results/results.xml
```
For the full option reference, run-name templates, and modes (new run vs existing), see [Result Upload](/docs/integrations/result-upload).
---
# WebdriverIO Integration
URL: /docs/cli-usage-webdriverio
See a working example: [bistro-e2e-wdio](https://github.com/Hypersequent/bistro-e2e-wdio) — WebdriverIO E2E tests with QA Sphere integration.
# WebdriverIO Integration
This guide covers WebdriverIO-specific setup. For install/auth/upload-command reference, see [Overview](/docs/cli), [Auth](/docs/cli/auth), and [Result Upload](/docs/integrations/result-upload).
## Prerequisites
* QAS CLI installed and authenticated — see the [Overview](/docs/cli). Node.js 22+ required for the CLI.
* WebdriverIO test project.
## Configure the JUnit reporter
```typescript
// wdio.conf.ts
import type { Options } from '@wdio/types';
export const config: Options.Testrunner = {
// ... other config
reporters: [
['junit', {
outputDir: './junit-results',
outputFileFormat: (options) => `results-${options.cid}-${options.capabilities.browserName}.xml`,
suiteNameFormat: /[^a-zA-Z0-9@\-:]+/ // Keeps alphanumeric, @, dash, colon
}]
],
};
```
WebdriverIO writes one JUnit XML per worker (e.g. `results-0-0.xml`, `results-0-1.xml`).
### Uploading multiple worker files
The upload commands accept multiple files. List them explicitly, or use a shell glob in bash/zsh:
```bash
npx qas-cli junit-upload junit-results/*.xml
```
## Mark tests with QA Sphere markers
WebdriverIO uses Mocha-style names, which support the hyphenated `PROJECT-SEQUENCE` marker. Place it at the start of the test name:
```typescript
// test/specs/cart-simple.e2e.ts
describe('Cart Functionality', () => {
it('BD-023: User should see product list on checkout page', async () => {
await browser.url('/checkout');
const products = await $$('.product-item');
expect(products.length).toBeGreaterThan(0);
});
it('BD-022: Order placement with valid data', async () => {
// ...
});
});
```
For all supported marker formats and matching rules, see [Result Upload — Test case matching](/docs/integrations/result-upload#test-case-matching).
## Attaching screenshots to failed tests
WebdriverIO doesn't reference screenshots in JUnit XML out of the box. Embed paths into the failure message via the `afterTest` hook, then `--attachments` picks them up:
```typescript
// wdio.conf.ts
import fs from 'fs/promises';
export const config: Options.Testrunner = {
// ... other config
afterTest: async function (test, context, { error, passed }) {
if (passed) return;
const testNamePrefix = test.title
.replace(/[^a-zA-Z0-9]+/g, '_')
.substring(0, 50);
const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
const finalScreenshot = `./screenshots/${testNamePrefix}_afterTest_${timestamp}.png`;
await browser.saveScreenshot(finalScreenshot);
const screenshotFiles = await fs.readdir('./screenshots');
const testCaseMatch = test.title.match(/^(BD-\d+)/);
const testCaseId = testCaseMatch ? testCaseMatch[1] : null;
const matchingScreenshots = screenshotFiles.filter(file =>
file.startsWith(testNamePrefix) || (testCaseId && file.includes(testCaseId))
);
if (error && matchingScreenshots.length > 0) {
const attachments = matchingScreenshots
.map(file => `[[ATTACHMENT|${file}]]`)
.join('\n');
error.message = `${error.message}\n\n${attachments}`;
}
},
};
```
The CLI recognizes the `[[ATTACHMENT|path]]` marker in failure messages and uploads the file alongside the result.
**Limitation**
This pattern only works for **failed** tests, since JUnit XML has no standard way to attach files to passing ones — the attachment marker lives inside `` / `` text.
Manual screenshots taken with `browser.saveScreenshot('./screenshots/BD-055_*.png')` during a test are matched by the test case ID and uploaded automatically when the test fails.
## Upload results
```bash
npm test
npx qas-cli junit-upload junit-results/*.xml
```
For the full option reference, run-name templates, and modes (new run vs existing), see [Result Upload](/docs/integrations/result-upload).
---
# December '24: 24W48
URL: /docs/24W48
QA Sphere 24W48 was released on Wednesday, December 10th 2024. It is available to all users of the platform.
## **New Features**
* **Custom Test Run Statuses**: You can now add up to four custom statuses for test run results (e.g., "Known Issue," "Retest," or "Passed w/remarks") to fit your workflow. Custom statuses are currently defined at the account level. They are fully supported across the product, including API and Reports.
* **Test Run Results**: A new setting, “Move to the next test case after adding the result,” simplifies filling out test runs by automatically advancing to the next test case.
```
**Options:**
* `-r, --run-url ` - Upload to an existing test run (otherwise creates a new run)
* `--run-name ` - Name template for creating new test runs (only used when `--run-url` is not specified)
* `--attachments` - Detect and upload attachments (screenshots, videos, logs)
* `--force` - Ignore API request errors, invalid test cases, or attachment issues
* `-h, --help` - Show command help
#### Run Name Template Placeholders
The `--run-name` option supports the following placeholders:
**Environment Variables:**
* `{env:VARIABLE_NAME}` - Any environment variable (e.g., `{env:BITBUCKET_BUILD_NUMBER}`, `{env:BITBUCKET_COMMIT}`)
**Date Placeholders:**
* `{YYYY}` - 4-digit year (e.g., 2025)
* `{YY}` - 2-digit year (e.g., 25)
* `{MMM}` - 3-letter month (e.g., Jan, Feb, Mar)
* `{MM}` - 2-digit month (e.g., 01, 02, 12)
* `{DD}` - 2-digit day (e.g., 01, 15, 31)
**Time Placeholders:**
* `{HH}` - 2-digit hour in 24-hour format (e.g., 00, 13, 23)
* `{hh}` - 2-digit hour in 12-hour format (e.g., 01, 12)
* `{mm}` - 2-digit minute (e.g., 00, 30, 59)
* `{ss}` - 2-digit second (e.g., 00, 30, 59)
* `{AMPM}` - AM/PM indicator
**Default Template:**
If `--run-name` is not specified, the default template is:
```
Automated test run - {MMM} {DD}, {YYYY}, {hh}:{mm}:{ss} {AMPM}
```
**Example Output:**
* `Automated test run - Jan 15, 2025, 02:30:45 PM`
The `--run-name` option is only used when creating new test runs (i.e., when `--run-url` is not specified).
**Usage Examples:**
```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
```
### Upload to Existing Test Run
To update a specific test run instead of creating a new one:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- |
RUN_ID=42
qasphere junit-upload \
-r ${QAS_URL}/project/BD/run/${RUN_ID} \
./junit-results/results.xml
```
### Upload with Attachments
Include screenshots and logs with your results:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- qasphere junit-upload --attachments ./junit-results/results.xml
```
The CLI automatically detects and uploads:
* Screenshots from test failures
* Video recordings
* Log files
* Any files referenced in the JUnit XML
### Upload Multiple XML Files
If you have multiple test suites generating separate XML files:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/*.xml
```
### Branch-Specific Runs
Create different runs for different branches:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- |
if [ "$BITBUCKET_BRANCH" = "main" ]; then
# Upload to production run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/100 ./junit-results/results.xml
elif [ "$BITBUCKET_BRANCH" = "develop" ]; then
# Upload to development run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/101 ./junit-results/results.xml
else
# Create new run for feature branches
qasphere junit-upload ./junit-results/results.xml
fi
```
### Add Pipeline Metadata
Use the `--run-name` option to include Bitbucket pipeline information in test run titles:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- |
qasphere junit-upload \
--run-name "Build #{env:BITBUCKET_BUILD_NUMBER} - {env:BITBUCKET_BRANCH}" \
./junit-results/results.xml
# Output: "Build #12345 - main"
```
**Common Bitbucket Variables:**
* `{env:BITBUCKET_BUILD_NUMBER}` - Pipeline build number
* `{env:BITBUCKET_BRANCH}` - Branch name
* `{env:BITBUCKET_COMMIT}` - Full commit SHA
* `{env:BITBUCKET_TAG}` - Tag name (if applicable)
* `{env:BITBUCKET_REPO_SLUG}` - Repository name
* `{env:BITBUCKET_STEP_TRIGGERER_UUID}` - User who triggered the pipeline
**Examples:**
```yaml
# Pipeline with date and time
- script: qasphere junit-upload --run-name "Build #{env:BITBUCKET_BUILD_NUMBER} - {YYYY}-{MM}-{DD} {HH}:{mm}" ./junit-results/results.xml
# Branch and commit info
- script: qasphere junit-upload --run-name "{env:BITBUCKET_BRANCH} - {env:BITBUCKET_COMMIT}" ./junit-results/results.xml
# Complete metadata
- script: qasphere junit-upload --run-name "Build #{env:BITBUCKET_BUILD_NUMBER} ({env:BITBUCKET_BRANCH}) - {MMM} {DD}, {hh}:{mm} {AMPM}" ./junit-results/results.xml
```
### Force Upload on Errors
Continue uploading even if some tests can't be matched:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- qasphere junit-upload --force ./junit-results/results.xml
```
## Common Scenarios
### Scenario 1: Nightly Test Runs
Run tests on a schedule and upload results with descriptive names:
```yaml
image: node:22
definitions:
steps:
- step: &test-step
name: Run Nightly Tests
image: mcr.microsoft.com/playwright:v1.62.1-jammy
script:
- npm ci
- npx playwright test
artifacts:
- junit-results/**
- step: &upload-step
name: Upload Results
script:
- npm install -g qas-cli
# Create run with date in the name
- qasphere junit-upload --run-name "Nightly Tests - {YYYY}-{MM}-{DD}" ./junit-results/results.xml
# Output: "Nightly Tests - 2025-01-15"
pipelines:
# Scheduled pipeline (configure in Bitbucket UI)
custom:
nightly:
- step: *test-step
- step: *upload-step
```
To create the schedule:
1. Go to **Repository settings** → **Pipelines** → **Schedules**
2. Click **Create schedule**
3. Select the `nightly` custom pipeline
4. Set schedule (e.g., daily at 2 AM)
### Scenario 2: Parallel Test Execution
Run tests in parallel and upload all results:
```yaml
image: node:22
definitions:
steps:
- step: &test-unit
name: Unit Tests
script:
- npm ci
- npm run test:unit
artifacts:
- junit-results/unit-results.xml
- step: &test-integration
name: Integration Tests
script:
- npm ci
- npm run test:integration
artifacts:
- junit-results/integration-results.xml
- step: &upload-step
name: Upload All Results
script:
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/*.xml
pipelines:
default:
- parallel:
- step: *test-unit
- step: *test-integration
- step: *upload-step
```
### Scenario 3: Multi-Environment Testing
Test against different environments:
```yaml
image: node:22
definitions:
steps:
- step: &test-staging
name: Test Staging
script:
- export TEST_ENV=staging
- export BASE_URL=https://staging.example.com
- npm ci
- npm test
artifacts:
- junit-results/staging-results.xml
- step: &test-production
name: Test Production
script:
- export TEST_ENV=production
- export BASE_URL=https://example.com
- npm ci
- npm test
artifacts:
- junit-results/production-results.xml
- step: &upload-step
name: Upload Results
script:
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/*.xml
pipelines:
default:
- parallel:
- step: *test-staging
- step: *test-production
- step: *upload-step
```
### Scenario 4: Version/Release Tagging
Tag test runs with version numbers or release names:
```yaml
image: node:22
definitions:
steps:
- step: &test-step
name: Run Release Tests
image: mcr.microsoft.com/playwright:v1.62.1-jammy
script:
- npm ci
- npx playwright test
artifacts:
- junit-results/**
- step: &upload-step
name: Upload Results
script:
- npm install -g qas-cli
- |
if [ -n "$BITBUCKET_TAG" ]; then
# For git tags, use tag name
qasphere junit-upload --run-name "Release {env:BITBUCKET_TAG}" ./junit-results/results.xml
else
# For regular commits, use branch and commit
SHORT_SHA=$(echo "$BITBUCKET_COMMIT" | cut -c1-7)
qasphere junit-upload --run-name "{env:BITBUCKET_BRANCH} - ${SHORT_SHA}" ./junit-results/results.xml
fi
pipelines:
tags:
'v*':
- step: *test-step
- step: *upload-step
branches:
main:
- step: *test-step
- step: *upload-step
```
## Troubleshooting
### Issue: Tests Not Appearing in QA Sphere
**Symptoms:**
* Upload succeeds but no results in QA Sphere
* "Test case not found" warnings in logs
**Solutions:**
1. **Ensure test cases exist in QA Sphere:**
* Check that `BD-001`, `BD-002`, etc. exist in your QA Sphere project
* Verify the project code matches (BD, PRJ, etc.)
2. **Check marker format:**
* Must be `PROJECT-NUMBER` format
* Examples: `BD-001`, `PRJ-123`, `TEST-456`
### Issue: Authentication Failed (401 Error)
**Symptoms:**
```
Error: Authentication failed (401)
```
**Solutions:**
1. **Verify API key is correct:**
* Go to QA Sphere → Settings → API Keys
* Check the key hasn't been deleted
* Regenerate if needed
2. **Check Bitbucket variables:**
* Repository settings → Repository variables
* Verify `QAS_TOKEN` is set correctly
* Ensure no extra spaces or line breaks
* Verify the "Secured" checkbox is enabled
3. **Verify key permissions:**
* API key must have Test Runner role or higher
* Check user permissions in QA Sphere
### Issue: JUnit XML File Not Found
**Symptoms:**
```
Error: File ./junit-results/results.xml does not exist
```
**Solutions:**
1. **Check test step artifacts:**
```yaml
- step:
name: Run Tests
script:
- npm ci
- npx playwright test
artifacts:
- junit-results/** # Make sure this matches your output path
```
2. **Verify test framework configuration:**
* Playwright: Check `playwright.config.js` reporter
* Cypress: Check `reporter-config.json`
* Jest: Check `jest.config.js` reporters
3. **Add debug output:**
```yaml
- step:
name: Upload to QA Sphere
script:
- ls -la junit-results/ # List files
- cat junit-results/results.xml # Show content
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/results.xml
```
### Issue: Playwright Version Mismatch
**Symptoms:**
```
Error: Executable doesn't exist at /ms-playwright/chromium...
╔ - current: mcr.microsoft.com/playwright:v1.40.0-jammy
║ - required: mcr.microsoft.com/playwright:v1.62.1-jammy
```
**Solution:**
Match Docker image version to your Playwright package version:
```bash
# Check your Playwright version
npm list @playwright/test
# Output: @playwright/test@1.62.1
```
```yaml
# Update bitbucket-pipelines.yml
- step:
name: Run Playwright Tests
image: mcr.microsoft.com/playwright:v1.62.1-jammy # Match the version
```
### Issue: Pipeline Fails But Tests Pass
**Symptoms:**
* Tests execute successfully
* Artifacts are uploaded
* Step still marked as failed
**Solution:**
Ensure test failures don't block artifact upload:
```yaml
- step:
name: Run Tests
script:
- npm ci
- npx playwright test || true # Continue even if tests fail
artifacts:
- junit-results/**
```
Or handle exit codes explicitly:
```yaml
- step:
name: Run Tests
script:
- npm ci
- |
set +e
npx playwright test
TEST_EXIT=$?
set -e
echo "Tests completed with exit code: $TEST_EXIT"
exit 0 # Force success to allow artifact upload
artifacts:
- junit-results/**
```
### Issue: Upload Step Doesn't Run
**Symptoms:**
* Test step completes
* Upload step never starts
**Solutions:**
1. **Check pipeline structure:**
```yaml
pipelines:
default:
- step:
name: Run Tests
script:
- npm test
artifacts:
- junit-results/**
- step: # This should run after the previous step
name: Upload Results
script:
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/results.xml
```
2. **Verify artifacts are defined:**
* Artifacts from the test step must be declared
* They're automatically available in subsequent steps
### Issue: Variables Not Available
**Symptoms:**
```
Error: QAS_TOKEN environment variable is not set
```
**Solutions:**
1. **Verify variables are defined:**
* Go to Repository settings → Repository variables
* Ensure `QAS_TOKEN` and `QAS_URL` exist
2. **Check variable usage in pipeline:**
```yaml
- step:
name: Upload to QA Sphere
script:
# Variables are automatically available as environment variables
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/results.xml
```
3. **For deployment variables:**
* If using deployment steps, ensure variables are available in that environment
* Check if variables need to be added to deployment environment settings
### Issue: Pipeline Doesn't Trigger
**Symptoms:**
* Push code but pipeline doesn't run
* Pipeline file exists but not executing
**Solutions:**
1. **Verify pipeline file location:**
```
bitbucket-pipelines.yml ✅ Correct (in repository root)
.bitbucket-pipelines.yml ❌ Wrong (no dot prefix)
pipelines/bitbucket-pipelines.yml ❌ Wrong (should be in root)
```
2. **Check YAML syntax:**
```bash
# Validate YAML locally
npx js-yaml bitbucket-pipelines.yml
```
3. **Verify pipelines are enabled:**
* Repository settings → Pipelines → Settings
* Ensure "Enable Pipelines" is checked
4. **Check branch configuration:**
```yaml
pipelines:
branches:
main: # Check branch names match exactly
- step:
name: Test
script:
- npm test
```
## Best Practices
### 1. Always Use Markers
Include QA Sphere markers in all automated tests:
```typescript
// ✅ Good
test('BD-001: User can login successfully', async ({ page }) => {});
// ❌ Bad - no marker
test('User can login successfully', async ({ page }) => {});
```
### 2. Upload on Every Pipeline Run
Configure upload to run even when tests fail by using `|| true` or proper exit code handling:
```yaml
- step:
name: Run Tests
script:
- npm ci
- npx playwright test || true
artifacts:
- junit-results/**
- step:
name: Upload Results
script:
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/results.xml
```
This ensures you track both passing and failing test results.
### 3. Use Descriptive Run Names
Use the `--run-name` option to create meaningful test run titles:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- |
qasphere junit-upload \
--run-name "Build #{env:BITBUCKET_BUILD_NUMBER} - {env:BITBUCKET_BRANCH}" \
./junit-results/results.xml
```
For branch-specific runs, you can also upload to existing runs:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- |
if [ "$BITBUCKET_BRANCH" = "main" ]; then
# Upload to production run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/100 ./junit-results/results.xml
elif [ "$BITBUCKET_BRANCH" = "develop" ]; then
# Upload to development run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/101 ./junit-results/results.xml
else
# Create new run for feature branches
SHORT_COMMIT=$(echo "$BITBUCKET_COMMIT" | cut -c1-7)
qasphere junit-upload --run-name "{env:BITBUCKET_BRANCH} - ${SHORT_COMMIT}" ./junit-results/results.xml
fi
```
### 4. Secure Your API Keys
* ✅ Store in Bitbucket Repository variables
* ✅ Enable "Secured" checkbox for sensitive values
* ✅ Rotate keys periodically
* ❌ Never commit to repository
* ❌ Never log or print in pipeline
### 5. Upload Attachments for Failures
Help debug failures by including screenshots:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- qasphere junit-upload --attachments ./junit-results/results.xml
```
### 6. Match Playwright Versions
Always keep Docker image version in sync with npm package:
```json
// package.json
{
"devDependencies": {
"@playwright/test": "1.62.1"
}
}
```
```yaml
# bitbucket-pipelines.yml
- step:
name: Run Tests
image: mcr.microsoft.com/playwright:v1.62.1-jammy
```
### 7. Use Caching for Faster Builds
Cache dependencies to speed up pipeline runs:
```yaml
definitions:
caches:
node: node_modules
- step:
name: Run Tests
caches:
- node
script:
- npm ci
- npx playwright test
```
### 8. Test Locally First
Before pushing to Bitbucket, test the integration locally:
```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
```
### 9. Monitor Upload Success
Add error handling to track upload status:
```yaml
- step:
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- |
if qasphere junit-upload ./junit-results/results.xml; then
echo "✅ Successfully uploaded results to QA Sphere"
else
echo "❌ Failed to upload results to QA Sphere"
exit 1
fi
```
### 10. Use Step Definitions
Define reusable steps for cleaner pipelines:
```yaml
definitions:
steps:
- step: &test
name: Run Tests
image: mcr.microsoft.com/playwright:v1.62.1-jammy
caches:
- node
script:
- npm ci
- npx playwright test
artifacts:
- junit-results/**
- step: &upload
name: Upload to QA Sphere
script:
- npm install -g qas-cli
- qasphere junit-upload --attachments ./junit-results/results.xml
pipelines:
default:
- step: *test
- step: *upload
```
## Complete Working Example
Here's a complete, production-ready configuration:
```yaml
# bitbucket-pipelines.yml
image: node:22
definitions:
caches:
node: node_modules
steps:
- step: &test
name: Run Playwright Tests
image: mcr.microsoft.com/playwright:v1.62.1-jammy
caches:
- node
script:
- npm ci
- npx playwright test || true # Continue even if tests fail
artifacts:
- junit-results/**
- test-results/**
- playwright-report/**
- step: &upload
name: Upload Results to QA Sphere
script:
- npm install -g qas-cli
# Verify results file exists
- test -f junit-results/results.xml || (echo "Results file not found" && exit 1)
# Upload with descriptive run name and attachments
- |
SHORT_COMMIT=$(echo "$BITBUCKET_COMMIT" | cut -c1-7)
qasphere junit-upload \
--run-name "Build #{env:BITBUCKET_BUILD_NUMBER} - {env:BITBUCKET_BRANCH} (${SHORT_COMMIT})" \
--attachments \
./junit-results/results.xml
- echo "✅ Test results uploaded to QA Sphere"
- echo "View at: ${QAS_URL}/project/BD/runs"
pipelines:
default:
- step: *test
- step: *upload
branches:
main:
- step: *test
- step: *upload
develop:
- step: *test
- step: *upload
pull-requests:
'**':
- step: *test
- step: *upload
custom:
nightly:
- step: *test
- step:
<<: *upload
name: Upload Nightly Results
script:
- npm install -g qas-cli
- test -f junit-results/results.xml || (echo "Results file not found" && exit 1)
- qasphere junit-upload --run-name "Nightly Tests - {YYYY}-{MM}-{DD}" --attachments ./junit-results/results.xml
```
## Next Steps
Once you have the basic integration working:
1. **Add More Tests** - Expand your test coverage with proper markers
2. **Set Up Schedules** - Run tests nightly using Bitbucket's scheduled pipelines
3. **Create Dashboards** - Use QA Sphere reports to track quality trends
4. **Configure Notifications** - Get alerts for test failures
5. **Integrate with Jira** - Link test failures to bug tickets (Bitbucket and Jira integrate natively)
## Additional Resources
* [QA Sphere CLI Documentation - Playwright Integration](/docs/cli-usage-playwright)
* [QA Sphere CLI Documentation - WebdriverIO Integration](/docs/cli-usage-webdriverio)
* [QA Sphere API Documentation](/docs/api/api_intro)
* [Authentication Guide](/docs/api/authentication)
* [Bitbucket Pipelines Documentation](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/)
* [Playwright Documentation](https://playwright.dev/)
## Getting Help
If you encounter issues:
1. Check the [Troubleshooting](#troubleshooting) section above
2. Review pipeline logs in Bitbucket
3. Test CLI locally with same configuration
4. Contact QA Sphere support: [sorted@qasphere.com](mailto:sorted@qasphere.com)
***
**Summary:** You now have everything you need to integrate QA Sphere with Bitbucket Pipelines. The QAS CLI tool automatically handles test result uploads, making test management seamless and automated. Every pipeline run will now update QA Sphere with the latest test results.
---
# GitHub Actions Integration
URL: /docs/integrations/ci-cd/github-actions
Automatically upload test results from your GitHub Actions workflows to QA Sphere using the QAS CLI tool. This integration eliminates manual result entry and provides instant visibility into your automated test results.
## What You'll Achieve
With this integration, every time your GitHub Actions workflow runs:
* Test results automatically upload to QA Sphere
* New test runs are created with workflow information
* Tests are matched to existing QA Sphere test cases
* Pass/fail status, execution time, and screenshots are recorded
* Test history and trends are tracked over time
## Prerequisites
Before starting, ensure you have:
* A GitHub repository with automated tests (Playwright, Cypress, Jest, etc.)
* Tests configured to generate **JUnit XML** format results
* A QA Sphere account with **Test Runner** role or higher
* Test cases in QA Sphere with **markers** (e.g., `BD-001`, `PRJ-123`)
## How It Works
```
**Options:**
* `-r, --run-url ` - Upload to an existing test run (otherwise creates a new run)
* `--run-name ` - Name template for creating new test runs (only used when `--run-url` is not specified)
* `--attachments` - Detect and upload attachments (screenshots, videos, logs)
* `--force` - Ignore API request errors, invalid test cases, or attachment issues
* `-h, --help` - Show command help
#### Run Name Template Placeholders
The `--run-name` option supports the following placeholders:
**Environment Variables:**
* `{env:VARIABLE_NAME}` - Any environment variable (e.g., `{env:GITHUB_RUN_NUMBER}`, `{env:GITHUB_SHA}`)
**Date Placeholders:**
* `{YYYY}` - 4-digit year (e.g., 2025)
* `{YY}` - 2-digit year (e.g., 25)
* `{MMM}` - 3-letter month (e.g., Jan, Feb, Mar)
* `{MM}` - 2-digit month (e.g., 01, 02, 12)
* `{DD}` - 2-digit day (e.g., 01, 15, 31)
**Time Placeholders:**
* `{HH}` - 2-digit hour in 24-hour format (e.g., 00, 13, 23)
* `{hh}` - 2-digit hour in 12-hour format (e.g., 01, 12)
* `{mm}` - 2-digit minute (e.g., 00, 30, 59)
* `{ss}` - 2-digit second (e.g., 00, 30, 59)
* `{AMPM}` - AM/PM indicator
**Default Template:**
If `--run-name` is not specified, the default template is:
```
Automated test run - {MMM} {DD}, {YYYY}, {hh}:{mm}:{ss} {AMPM}
```
**Example Output:**
* `Automated test run - Jan 15, 2025, 02:30:45 PM`
The `--run-name` option is only used when creating new test runs (i.e., when `--run-url` is not specified).
**Usage Examples:**
```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 "Run #{env:GITHUB_RUN_NUMBER} - {env:GITHUB_REF_NAME}" ./junit-results/results.xml
# Output: "Run #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
```
### Upload to Existing Test Run
To update a specific test run instead of creating a new one:
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
RUN_ID=42
qasphere junit-upload \
-r ${QAS_URL}/project/BD/run/${RUN_ID} \
./junit-results/results.xml
```
### Upload with Attachments
Include screenshots and logs with your results:
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: qasphere junit-upload --attachments ./junit-results/results.xml
```
The CLI automatically detects and uploads:
* Screenshots from test failures
* Video recordings
* Log files
* Any files referenced in the JUnit XML
### Upload Multiple XML Files
If you have multiple test suites generating separate XML files:
```yaml
- name: Upload to QA Sphere
run: qasphere junit-upload ./junit-results/*.xml
```
### Branch-Specific Runs
Create different runs for different branches:
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
if [ "${{ github.ref_name }}" = "main" ]; then
# Upload to production run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/100 ./junit-results/results.xml
elif [ "${{ github.ref_name }}" = "develop" ]; then
# Upload to development run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/101 ./junit-results/results.xml
else
# Create new run for feature branches
qasphere junit-upload ./junit-results/results.xml
fi
```
### Add Workflow Metadata
Use the `--run-name` option to include GitHub workflow information in test run titles:
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
qasphere junit-upload \
--run-name "Run #{env:GITHUB_RUN_NUMBER} - {env:GITHUB_REF_NAME}" \
./junit-results/results.xml
# Output: "Run #12345 - main"
```
**Common GitHub Variables:**
* `{env:GITHUB_RUN_NUMBER}` - Workflow run number
* `{env:GITHUB_REF_NAME}` - Branch or tag name
* `{env:GITHUB_SHA}` - Commit SHA (full)
* `{env:GITHUB_ACTOR}` - User who triggered the workflow
* `{env:GITHUB_JOB}` - Current job name
* `{env:GITHUB_WORKFLOW}` - Workflow name
**Examples:**
```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
```
### Force Upload on Errors
Continue uploading even if some tests can't be matched:
```yaml
- name: Upload to QA Sphere
run: qasphere junit-upload --force ./junit-results/results.xml
```
## Common Scenarios
### Scenario 1: Nightly Test Runs
Run tests on a schedule and upload results with descriptive names:
```yaml
name: Nightly Tests
on:
schedule:
- cron: '0 2 * * *' # Run at 2 AM UTC daily
workflow_dispatch:
jobs:
test:
name: Run Nightly Tests
runs-on: ubuntu-latest
# ... test steps ...
upload-to-qasphere:
name: Upload Results
runs-on: ubuntu-latest
needs: test
if: always()
steps:
- name: Download test results
uses: actions/download-artifact@v4
with:
name: junit-results
path: junit-results/
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install QAS CLI
run: npm install -g qas-cli
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
# Create run with date in the name
qasphere junit-upload --run-name "Nightly Tests - {YYYY}-{MM}-{DD}" ./junit-results/results.xml
# Output: "Nightly Tests - 2025-01-15"
# Or with time included
qasphere junit-upload --run-name "Nightly {MMM} {DD}, {YYYY} at {HH}:{mm}" ./junit-results/results.xml
# Output: "Nightly Jan 15, 2025 at 22:30"
```
### Scenario 2: Parallel Test Execution
Run tests in parallel using matrix strategy and upload all results:
```yaml
name: Parallel Tests
on:
push:
branches: [main, develop]
jobs:
test:
name: Test - ${{ matrix.suite }}
runs-on: ubuntu-latest
strategy:
matrix:
suite: [unit, integration, e2e]
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install dependencies
run: npm ci
- name: Run ${{ matrix.suite }} tests
run: npm run test:${{ matrix.suite }}
continue-on-error: true
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: junit-results-${{ matrix.suite }}
path: junit-results/
retention-days: 7
upload-to-qasphere:
name: Upload Results to QA Sphere
runs-on: ubuntu-latest
needs: test
if: always()
steps:
- name: Download all test results
uses: actions/download-artifact@v4
with:
pattern: junit-results-*
path: junit-results/
merge-multiple: true
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install QAS CLI
run: npm install -g qas-cli
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: qasphere junit-upload ./junit-results/*.xml
```
### Scenario 3: Multi-Environment Testing
Test against different environments:
```yaml
name: Multi-Environment Tests
on:
push:
branches: [main, develop]
jobs:
test:
name: Test - ${{ matrix.environment }}
runs-on: ubuntu-latest
strategy:
matrix:
environment: [staging, production]
include:
- environment: staging
base_url: https://staging.example.com
- environment: production
base_url: https://example.com
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install dependencies
run: npm ci
- name: Run tests
env:
BASE_URL: ${{ matrix.base_url }}
TEST_ENV: ${{ matrix.environment }}
run: npm test
continue-on-error: true
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: junit-results-${{ matrix.environment }}
path: junit-results/
retention-days: 7
upload-to-qasphere:
name: Upload Results
runs-on: ubuntu-latest
needs: test
if: always()
steps:
- name: Download all test results
uses: actions/download-artifact@v4
with:
pattern: junit-results-*
path: junit-results/
merge-multiple: true
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install QAS CLI
run: npm install -g qas-cli
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: qasphere junit-upload ./junit-results/*.xml
```
### Scenario 4: Version/Release Tagging
Tag test runs with version numbers or release names:
```yaml
name: Release Tests
on:
push:
tags:
- 'v*'
workflow_dispatch:
env:
VERSION: ${{ github.ref_name }}
jobs:
test:
name: Run Release Tests
runs-on: ubuntu-latest
# ... test steps ...
upload-to-qasphere:
name: Upload Results
runs-on: ubuntu-latest
needs: test
if: always()
steps:
- name: Download test results
uses: actions/download-artifact@v4
with:
name: junit-results
path: junit-results/
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install QAS CLI
run: npm install -g qas-cli
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
# Simple version tag
qasphere junit-upload --run-name "Release {env:VERSION}" ./junit-results/results.xml
# Output: "Release v1.4.5"
# Version with date
qasphere junit-upload --run-name "Release {env:VERSION} - {YYYY}-{MM}-{DD}" ./junit-results/results.xml
# Output: "Release v1.4.5 - 2025-01-15"
```
For different handling of tags vs branches:
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
if [ "${{ github.ref_type }}" = "tag" ]; then
# For git tags, use tag name
qasphere junit-upload --run-name "Release {env:GITHUB_REF_NAME}" ./junit-results/results.xml
else
# For regular commits, use branch and commit
SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
qasphere junit-upload --run-name "{env:GITHUB_REF_NAME} - ${SHORT_SHA}" ./junit-results/results.xml
fi
```
## Troubleshooting
### Issue: Tests Not Appearing in QA Sphere
**Symptoms:**
* Upload succeeds but no results in QA Sphere
* "Test case not found" warnings in logs
**Solutions:**
1. **Ensure test cases exist in QA Sphere:**
* Check that `BD-001`, `BD-002`, etc. exist in your QA Sphere project
* Verify the project code matches (BD, PRJ, etc.)
2. **Check marker format:**
* Must be `PROJECT-NUMBER` format
* Examples: `BD-001`, `PRJ-123`, `TEST-456`
### Issue: Authentication Failed (401 Error)
**Symptoms:**
```
Error: Authentication failed (401)
```
**Solutions:**
1. **Verify API key is correct:**
* Go to QA Sphere → Settings → API Keys
* Check the key hasn't been deleted
* Regenerate if needed
2. **Check GitHub Secrets:**
* Settings → Secrets and variables → Actions
* Verify `QAS_TOKEN` is set correctly
* Ensure no extra spaces or line breaks
3. **Verify key permissions:**
* API key must have Test Runner role or higher
* Check user permissions in QA Sphere
### Issue: JUnit XML File Not Found
**Symptoms:**
```
Error: File ./junit-results/results.xml does not exist
```
**Solutions:**
1. **Check artifact upload configuration:**
```yaml
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: junit-results
path: junit-results/ # Make sure this matches your output path
```
2. **Verify test framework configuration:**
* Playwright: Check `playwright.config.js` reporter
* Cypress: Check `reporter-config.json`
* Jest: Check `jest.config.js` reporters
3. **Add debug output:**
```yaml
- name: Debug - List files
run: |
ls -la junit-results/
cat junit-results/results.xml
- name: Upload to QA Sphere
run: qasphere junit-upload ./junit-results/results.xml
```
### Issue: Artifact Not Found
**Symptoms:**
```
Error: Unable to find any artifacts for the associated workflow
```
**Solutions:**
1. **Ensure artifact names match:**
```yaml
# In test job
- name: Upload test results
uses: actions/upload-artifact@v4
with:
name: junit-results # Must match
# In upload job
- name: Download test results
uses: actions/download-artifact@v4
with:
name: junit-results # Must match
```
2. **Check job dependencies:**
```yaml
upload-to-qasphere:
needs: test # Must reference the correct job name
if: always() # Run even if test job fails
```
### Issue: Playwright Version Mismatch
**Symptoms:**
```
Error: Executable doesn't exist at /ms-playwright/chromium...
```
**Solution:**
Match Docker image version to your Playwright package version:
```bash
# Check your Playwright version
npm list @playwright/test
# Output: @playwright/test@1.62.1
```
```yaml
# Update workflow file
jobs:
test:
container:
image: mcr.microsoft.com/playwright:v1.62.1-jammy # Match the version
```
### Issue: Secrets Not Available
**Symptoms:**
```
Error: QAS_TOKEN environment variable is not set
```
**Solutions:**
1. **Verify secrets are defined:**
* Go to repository Settings → Secrets and variables → Actions
* Ensure `QAS_TOKEN` and `QAS_URL` exist
2. **Check secret usage in workflow:**
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }} # Correct syntax
QAS_URL: ${{ secrets.QAS_URL }}
run: qasphere junit-upload ./junit-results/results.xml
```
3. **For organization secrets:**
* Ensure repository has access to organization secrets
* Check secret visibility settings
### Issue: Workflow Doesn't Trigger
**Symptoms:**
* Push code but workflow doesn't run
* Workflow file exists but not visible in Actions tab
**Solutions:**
1. **Verify workflow file location:**
```
.github/workflows/qa-sphere-tests.yml ✅ Correct
.github/workflow/qa-sphere-tests.yml ❌ Wrong (missing 's')
github/workflows/qa-sphere-tests.yml ❌ Wrong (missing '.')
```
2. **Check YAML syntax:**
```bash
# Validate YAML locally
npx js-yaml .github/workflows/qa-sphere-tests.yml
```
3. **Verify trigger configuration:**
```yaml
on:
push:
branches: [main, develop] # Check branch names match
pull_request:
branches: [main, develop]
```
4. **Check branch protection rules:**
* Repository Settings → Branches
* Ensure Actions aren't blocked by branch protection
## Best Practices
### 1. Always Use Markers
Include QA Sphere markers in all automated tests:
```typescript
// ✅ Good
test('BD-001: User can login successfully', async ({ page }) => {});
// ❌ Bad - no marker
test('User can login successfully', async ({ page }) => {});
```
### 2. Upload on Every Workflow Run
Configure upload to run even when tests fail:
```yaml
upload-to-qasphere:
needs: test
if: always() # Run even if test job fails
```
This ensures you track both passing and failing test results.
### 3. Use Descriptive Run Names
Use the `--run-name` option to create meaningful test run titles:
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
qasphere junit-upload \
--run-name "Run #{env:GITHUB_RUN_NUMBER} - {env:GITHUB_REF_NAME}" \
./junit-results/results.xml
```
For branch-specific runs, you can also upload to existing runs:
```yaml
- name: Upload to QA Sphere
run: |
if [ "${{ github.ref_name }}" = "main" ]; then
# Upload to production run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/100 ./junit-results/results.xml
elif [ "${{ github.ref_name }}" = "develop" ]; then
# Upload to development run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/101 ./junit-results/results.xml
else
# Create new run for feature branches
SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
qasphere junit-upload --run-name "{env:GITHUB_REF_NAME} - ${SHORT_SHA}" ./junit-results/results.xml
fi
```
### 4. Secure Your API Keys
* ✅ Store in GitHub Secrets
* ✅ Use repository or organization secrets
* ✅ Rotate keys periodically
* ❌ Never commit to repository
* ❌ Never log or print in workflow
### 5. Upload Attachments for Failures
Help debug failures by including screenshots:
```yaml
- name: Upload to QA Sphere
run: qasphere junit-upload --attachments ./junit-results/results.xml
```
### 6. Match Playwright Versions
Always keep Docker image version in sync with npm package:
```json
// package.json
{
"devDependencies": {
"@playwright/test": "1.62.1"
}
}
```
```yaml
# .github/workflows/qa-sphere-tests.yml
jobs:
test:
container:
image: mcr.microsoft.com/playwright:v1.62.1-jammy
```
### 7. Use Caching for Faster Builds
Cache dependencies to speed up workflow runs:
```yaml
- name: Cache node modules
uses: actions/cache@v4
with:
path: |
~/.npm
node_modules
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
```
### 8. Use Concurrency Controls
Prevent redundant workflow runs for the same branch:
```yaml
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
```
### 9. Test Locally First
Before pushing to GitHub, test the integration locally:
```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
```
### 10. Monitor Upload Success
Add error handling to track upload status:
```yaml
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
if qasphere junit-upload ./junit-results/results.xml; then
echo "✅ Successfully uploaded results to QA Sphere"
else
echo "❌ Failed to upload results to QA Sphere"
exit 1
fi
```
### 11. Set Appropriate Artifact Retention
Balance storage costs with retention needs:
```yaml
- name: Upload test results
uses: actions/upload-artifact@v4
with:
name: junit-results
path: junit-results/
retention-days: 7 # Adjust based on your needs (1-90 days)
```
## Complete Working Example
Here's a complete, production-ready configuration:
```yaml
# .github/workflows/qa-sphere-tests.yml
name: QA Sphere Integration
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
workflow_dispatch:
# Prevent redundant runs for the same branch
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
PLAYWRIGHT_VERSION: "1.62.1"
jobs:
test:
name: Run Playwright Tests
runs-on: ubuntu-latest
container:
image: mcr.microsoft.com/playwright:v1.62.1-jammy
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Cache node modules
uses: actions/cache@v4
with:
path: node_modules
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
- name: Install dependencies
run: npm ci
- name: Run Playwright tests
run: npx playwright test
continue-on-error: true
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: junit-results
path: junit-results/
retention-days: 7
- name: Upload test artifacts
uses: actions/upload-artifact@v4
if: always()
with:
name: test-artifacts
path: |
test-results/
playwright-report/
retention-days: 7
upload-to-qasphere:
name: Upload Results to QA Sphere
runs-on: ubuntu-latest
needs: test
if: always()
steps:
- name: Download test results
uses: actions/download-artifact@v4
with:
name: junit-results
path: junit-results/
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
cache: 'npm'
- name: Install QAS CLI
run: npm install -g qas-cli
- name: Verify results file exists
run: test -f junit-results/results.xml || (echo "Results file not found" && exit 1)
- name: Upload to QA Sphere
env:
QAS_TOKEN: ${{ secrets.QAS_TOKEN }}
QAS_URL: ${{ secrets.QAS_URL }}
run: |
SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
qasphere junit-upload \
--run-name "Run #{env:GITHUB_RUN_NUMBER} - {env:GITHUB_REF_NAME} (${SHORT_SHA})" \
--attachments \
./junit-results/results.xml
- name: Workflow Summary
if: always()
run: |
echo "## QA Sphere Upload Summary" >> $GITHUB_STEP_SUMMARY
echo "✅ Test results uploaded to QA Sphere" >> $GITHUB_STEP_SUMMARY
echo "**View results:** ${{ secrets.QAS_URL }}/project/BD/runs" >> $GITHUB_STEP_SUMMARY
echo "**Workflow:** Run #${{ github.run_number }}" >> $GITHUB_STEP_SUMMARY
echo "**Branch:** ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
echo "**Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
```
## Additional Resources
* [QA Sphere CLI Documentation - Playwright Integration](/docs/cli-usage-playwright)
* [QA Sphere CLI Documentation - WebdriverIO Integration](/docs/cli-usage-webdriverio)
* [QA Sphere API Documentation](/docs/api/api_intro)
* [Authentication Guide](/docs/api/authentication)
* [GitHub Actions Documentation](https://docs.github.com/en/actions)
* [Playwright Documentation](https://playwright.dev/)
## Getting Help
If you encounter issues:
1. Check the [Troubleshooting](#troubleshooting) section above
2. Review workflow logs in GitHub Actions
3. Test CLI locally with same configuration
4. Check GitHub Actions workflow syntax
5. Contact QA Sphere support: [sorted@qasphere.com](mailto:sorted@qasphere.com)
***
**Summary:** You now have everything you need to integrate QA Sphere with GitHub Actions. The QAS CLI tool automatically handles test result uploads, making test management seamless and automated. Every workflow run will now update QA Sphere with the latest test results.
---
# GitLab CI/CD Integration
URL: /docs/integrations/ci-cd/gitlab
Automatically upload test results from your GitLab CI/CD pipelines to QA Sphere using the QAS CLI tool. This integration eliminates manual result entry and provides instant visibility into your automated test results.
## What You'll Achieve
With this integration, every time your GitLab pipeline runs:
* Test results automatically upload to QA Sphere
* New test runs are created with pipeline information
* Tests are matched to existing QA Sphere test cases
* Pass/fail status, execution time, and screenshots are recorded
* Test history and trends are tracked over time
## Prerequisites
Before starting, ensure you have:
* A GitLab project with automated tests (Playwright, Cypress, Jest, etc.)
* Tests configured to generate **JUnit XML** format results
* A QA Sphere account with **Test Runner** role or higher
* Test cases in QA Sphere with **markers** (e.g., `BD-001`, `PRJ-123`)
## How It Works
```
**Options:**
* `-r, --run-url ` - Upload to an existing test run (otherwise creates a new run)
* `--run-name ` - Name template for creating new test runs (only used when `--run-url` is not specified)
* `--attachments` - Detect and upload attachments (screenshots, videos, logs)
* `--force` - Ignore API request errors, invalid test cases, or attachment issues
* `-h, --help` - Show command help
#### Run Name Template Placeholders
The `--run-name` option supports the following placeholders:
**Environment Variables:**
* `{env:VARIABLE_NAME}` - Any environment variable (e.g., `{env:CI_PIPELINE_ID}`, `{env:CI_COMMIT_SHA}`)
**Date Placeholders:**
* `{YYYY}` - 4-digit year (e.g., 2025)
* `{YY}` - 2-digit year (e.g., 25)
* `{MMM}` - 3-letter month (e.g., Jan, Feb, Mar)
* `{MM}` - 2-digit month (e.g., 01, 02, 12)
* `{DD}` - 2-digit day (e.g., 01, 15, 31)
**Time Placeholders:**
* `{HH}` - 2-digit hour in 24-hour format (e.g., 00, 13, 23)
* `{hh}` - 2-digit hour in 12-hour format (e.g., 01, 12)
* `{mm}` - 2-digit minute (e.g., 00, 30, 59)
* `{ss}` - 2-digit second (e.g., 00, 30, 59)
* `{AMPM}` - AM/PM indicator
**Default Template:**
If `--run-name` is not specified, the default template is:
```
Automated test run - {MMM} {DD}, {YYYY}, {hh}:{mm}:{ss} {AMPM}
```
**Example Output:**
* `Automated test run - Jan 15, 2025, 02:30:45 PM`
The `--run-name` option is only used when creating new test runs (i.e., when `--run-url` is not specified).
**Usage Examples:**
```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
```
### Upload to Existing Test Run
To update a specific test run instead of creating a new one:
```yaml
upload-to-qasphere:
script:
- |
RUN_ID=42 # Your run ID
qasphere junit-upload \
-r ${QAS_URL}/project/BD/run/${RUN_ID} \
./junit-results/results.xml
```
### Upload with Attachments
Include screenshots and logs with your results:
```yaml
upload-to-qasphere:
script:
- qasphere junit-upload --attachments ./junit-results/results.xml
```
The CLI automatically detects and uploads:
* Screenshots from test failures
* Video recordings
* Log files
* Any files referenced in the JUnit XML
### Upload Multiple XML Files
If you have multiple test suites generating separate XML files:
```yaml
upload-to-qasphere:
script:
- qasphere junit-upload ./junit-results/*.xml
```
### Branch-Specific Runs
Create different runs for different branches:
```yaml
upload-to-qasphere:
script:
- |
if [ "$CI_COMMIT_REF_NAME" = "main" ]; then
# Upload to production run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/100 ./junit-results/results.xml
elif [ "$CI_COMMIT_REF_NAME" = "develop" ]; then
# Upload to development run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/101 ./junit-results/results.xml
else
# Create new run for feature branches
qasphere junit-upload ./junit-results/results.xml
fi
```
### Add Pipeline Metadata
Use the `--run-name` option to include GitLab pipeline information in test run titles:
```yaml
upload-to-qasphere:
script:
# Include pipeline ID and branch name
- |
qasphere junit-upload \
--run-name "Pipeline #{env:CI_PIPELINE_ID} - {env:CI_COMMIT_REF_NAME}" \
./junit-results/results.xml
# Output: "Pipeline #12345 - main"
```
**Common GitLab Variables:**
* `{env:CI_PIPELINE_ID}` - Pipeline ID number
* `{env:CI_COMMIT_REF_NAME}` - Branch or tag name
* `{env:CI_COMMIT_SHORT_SHA}` - Short commit SHA
* `{env:CI_COMMIT_SHA}` - Full commit SHA
* `{env:GITLAB_USER_NAME}` - User who triggered the pipeline
* `{env:CI_JOB_NAME}` - Current job name
**Examples:**
```yaml
# Pipeline with date and time
- qasphere junit-upload --run-name "Pipeline #{env:CI_PIPELINE_ID} - {YYYY}-{MM}-{DD} {HH}:{mm}" ./junit-results/results.xml
# Branch and commit info
- qasphere junit-upload --run-name "{env:CI_COMMIT_REF_NAME} - {env:CI_COMMIT_SHORT_SHA}" ./junit-results/results.xml
# Complete metadata
- qasphere junit-upload --run-name "Build #{env:CI_PIPELINE_ID} ({env:CI_COMMIT_REF_NAME}) - {MMM} {DD}, {hh}:{mm} {AMPM}" ./junit-results/results.xml
```
### Force Upload on Errors
Continue uploading even if some tests can't be matched:
```yaml
upload-to-qasphere:
script:
- qasphere junit-upload --force ./junit-results/results.xml
```
## Common Scenarios
### Scenario 1: Nightly Test Runs
Run tests on a schedule and upload results with descriptive names:
```yaml
test:
rules:
- if: $CI_PIPELINE_SOURCE == "schedule" # Only run on scheduled pipelines
- if: $CI_COMMIT_BRANCH == "main"
upload-to-qasphere:
script:
# Create run with date in the name
- qasphere junit-upload --run-name "Nightly Tests - {YYYY}-{MM}-{DD}" ./junit-results/results.xml
# Output: "Nightly Tests - 2025-01-15"
# Or with time included
- qasphere junit-upload --run-name "Nightly {MMM} {DD}, {YYYY} at {HH}:{mm}" ./junit-results/results.xml
# Output: "Nightly Jan 15, 2025 at 22:30"
```
Create the schedule in GitLab: **CI/CD** → **Schedules** → **New schedule**
### Scenario 2: Parallel Test Execution
Run tests in parallel and upload all results:
```yaml
test-unit:
stage: test
script:
- npm run test:unit
artifacts:
paths:
- junit-results/unit-results.xml
test-integration:
stage: test
script:
- npm run test:integration
artifacts:
paths:
- junit-results/integration-results.xml
upload-to-qasphere:
stage: report
needs:
- job: test-unit
artifacts: true
- job: test-integration
artifacts: true
script:
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/*.xml
```
### Scenario 3: Multi-Environment Testing
Test against different environments:
```yaml
test-staging:
variables:
TEST_ENV: "staging"
BASE_URL: "https://staging.example.com"
script:
- npm test
artifacts:
paths:
- junit-results/staging-results.xml
test-production:
variables:
TEST_ENV: "production"
BASE_URL: "https://example.com"
script:
- npm test
artifacts:
paths:
- junit-results/production-results.xml
upload-to-qasphere:
script:
- npm install -g qas-cli
- qasphere junit-upload ./junit-results/*.xml
```
### Scenario 4: Version/Release Tagging
Tag test runs with version numbers or release names:
```yaml
variables:
VERSION: "v1.4.5"
upload-to-qasphere:
script:
# Simple version tag
- qasphere junit-upload --run-name "Release {env:VERSION}" ./junit-results/results.xml
# Output: "Release v1.4.5"
# Version with date
- qasphere junit-upload --run-name "Release {env:VERSION} - {YYYY}-{MM}-{DD}" ./junit-results/results.xml
# Output: "Release v1.4.5 - 2025-01-15"
# Pre-release/RC builds
- qasphere junit-upload --run-name "{env:VERSION}-rc{env:CI_PIPELINE_ID}" ./junit-results/results.xml
# Output: "v1.4.5-rc12345"
```
For tagged releases in GitLab:
```yaml
upload-to-qasphere:
script:
- |
if [ -n "$CI_COMMIT_TAG" ]; then
# For git tags, use tag name
qasphere junit-upload --run-name "Release {env:CI_COMMIT_TAG}" ./junit-results/results.xml
else
# For regular commits, use branch and commit
qasphere junit-upload --run-name "{env:CI_COMMIT_REF_NAME} - {env:CI_COMMIT_SHORT_SHA}" ./junit-results/results.xml
fi
rules:
- if: $CI_COMMIT_TAG
- if: $CI_COMMIT_BRANCH == "main"
```
## Troubleshooting
### Issue: Tests Not Appearing in QA Sphere
**Symptoms:**
* Upload succeeds but no results in QA Sphere
* "Test case not found" warnings in logs
**Solutions:**
1. **Ensure test cases exist in QA Sphere:**
* Check that `BD-001`, `BD-002`, etc. exist in your QA Sphere project
* Verify the project code matches (BD, PRJ, etc.)
2. **Check marker format:**
* Must be `PROJECT-NUMBER` format
* Examples: `BD-001`, `PRJ-123`, `TEST-456`
### Issue: Authentication Failed (401 Error)
**Symptoms:**
```
Error: Authentication failed (401)
```
**Solutions:**
1. **Verify API key is correct:**
* Go to QA Sphere → Settings → API Keys
* Check the key hasn't been deleted
* Regenerate if needed
2. **Check GitLab variables:**
* Settings → CI/CD → Variables
* Verify `QAS_TOKEN` is set correctly
* Ensure no extra spaces or line breaks
3. **Verify key permissions:**
* API key must have Test Runner role or higher
* Check user permissions in QA Sphere
### Issue: JUnit XML File Not Found
**Symptoms:**
```
Error: File ./junit-results/results.xml does not exist
```
**Solutions:**
1. **Check test job artifacts:**
```yaml
test:
artifacts:
paths:
- junit-results/ # Make sure this matches your output path
```
2. **Verify test framework configuration:**
* Playwright: Check `playwright.config.js` reporter
* Cypress: Check `reporter-config.json`
* Jest: Check `jest.config.js` reporters
3. **Add debug output:**
```yaml
upload-to-qasphere:
script:
- ls -la junit-results/ # List files
- cat junit-results/results.xml # Show content
- qasphere junit-upload ./junit-results/results.xml
```
### Issue: Playwright Version Mismatch
**Symptoms:**
```
Error: Executable doesn't exist at /ms-playwright/chromium...
║ - current: mcr.microsoft.com/playwright:v1.40.0-jammy
║ - required: mcr.microsoft.com/playwright:v1.62.1-jammy
```
**Solution:**
Match Docker image version to your Playwright package version:
```bash
# Check your Playwright version
npm list @playwright/test
# Output: @playwright/test@1.62.1
```
```yaml
# Update .gitlab-ci.yml
test:
image: mcr.microsoft.com/playwright:v1.62.1-jammy # Match the version
```
### Issue: Pipeline Fails But Tests Pass
**Symptoms:**
* Tests execute successfully
* Artifacts are uploaded
* Job still marked as failed
**Solution:**
Force job success while preserving test results:
```yaml
test:
script:
- npm ci
- |
set +e
npx playwright test
TEST_EXIT=$?
set -e
echo "Tests completed with exit code: $TEST_EXIT"
exit 0 # Force success
artifacts:
when: always
paths:
- junit-results/
```
### Issue: Upload Job Doesn't Run
**Symptoms:**
* Test job completes
* Upload job never starts
**Solutions:**
1. **Check needs configuration:**
```yaml
upload-to-qasphere:
needs:
- job: test # Must match test job name exactly
artifacts: true
```
2. **Verify branch rules:**
```yaml
upload-to-qasphere:
rules:
- if: $CI_COMMIT_BRANCH == "main"
- if: $CI_COMMIT_BRANCH == "develop"
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
```
3. **Check `when` clause:**
```yaml
upload-to-qasphere:
when: always # Run even if test job fails
```
## Best Practices
### 1. Always Use Markers
Include QA Sphere markers in all automated tests:
```typescript
// ✅ Good
test('BD-001: User can login successfully', async ({ page }) => {});
// ❌ Bad - no marker
test('User can login successfully', async ({ page }) => {});
```
### 2. Upload on Every Pipeline Run
Configure upload to run even when tests fail:
```yaml
upload-to-qasphere:
when: always
allow_failure: true
```
This ensures you track both passing and failing test results.
### 3. Use Descriptive Run Names
Use the `--run-name` option to create meaningful test run titles:
```yaml
upload-to-qasphere:
script:
# Include pipeline and branch information
- |
qasphere junit-upload \
--run-name "Pipeline #{env:CI_PIPELINE_ID} - {env:CI_COMMIT_REF_NAME}" \
./junit-results/results.xml
```
For branch-specific runs, you can also upload to existing runs:
```yaml
script:
- |
if [ "$CI_COMMIT_REF_NAME" = "main" ]; then
# Upload to production run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/100 ./junit-results/results.xml
elif [ "$CI_COMMIT_REF_NAME" = "develop" ]; then
# Upload to development run
qasphere junit-upload -r ${QAS_URL}/project/BD/run/101 ./junit-results/results.xml
else
# Create new run for feature branches
qasphere junit-upload --run-name "{env:CI_COMMIT_REF_NAME} - {env:CI_COMMIT_SHORT_SHA}" ./junit-results/results.xml
fi
```
### 4. Secure Your API Keys
* Store in GitLab CI/CD variables
* Mark as Protected and Masked
* Rotate keys periodically
* Never commit to repository
* Never log or print in pipeline
### 5. Upload Attachments for Failures
Help debug failures by including screenshots:
```yaml
script:
- qasphere junit-upload --attachments ./junit-results/results.xml
```
### 6. Match Playwright Versions
Always keep Docker image version in sync with npm package:
```json
// package.json
{
"devDependencies": {
"@playwright/test": "1.62.1"
}
}
```
```yaml
# .gitlab-ci.yml
image: mcr.microsoft.com/playwright:v1.62.1-jammy
```
### 7. Test Locally First
Before pushing to GitLab, test the integration locally:
```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
```
### 8. Monitor Upload Success
Add logging to track upload status:
```yaml
upload-to-qasphere:
script:
- npm install -g qas-cli
- |
if qasphere junit-upload ./junit-results/results.xml; then
echo "✅ Successfully uploaded results to QA Sphere"
else
echo "❌ Failed to upload results to QA Sphere"
exit 1
fi
```
## Complete Working Example
Here's a complete, production-ready configuration:
```yaml
# .gitlab-ci.yml
stages:
- test
- report
variables:
HUSKY: 0
PLAYWRIGHT_VERSION: "1.62.1"
# Cache node modules for faster builds
cache:
paths:
- node_modules/
# Run Playwright tests
test:
stage: test
image: mcr.microsoft.com/playwright:v${PLAYWRIGHT_VERSION}-jammy
before_script:
- npm ci
script:
- npx playwright test
artifacts:
when: always
paths:
- junit-results/
- test-results/
- playwright-report/
reports:
junit: junit-results/results.xml
expire_in: 1 week
retry:
max: 1
when:
- runner_system_failure
rules:
- if: $CI_COMMIT_BRANCH == "main"
- if: $CI_COMMIT_BRANCH == "develop"
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
tags:
- docker
# Upload results to QA Sphere
upload-to-qasphere:
stage: report
image: node:22
needs:
- job: test
artifacts: true
before_script:
- npm install -g qas-cli
script:
# Verify file exists
- test -f junit-results/results.xml || (echo "Results file not found" && exit 1)
# Upload with descriptive run name and attachments
- |
qasphere junit-upload \
--run-name "Pipeline #{env:CI_PIPELINE_ID} - {env:CI_COMMIT_REF_NAME} ({env:CI_COMMIT_SHORT_SHA})" \
--attachments \
./junit-results/results.xml
- echo "✅ Test results uploaded to QA Sphere"
- echo "View at: ${QAS_URL}/project/BD/runs"
when: always
allow_failure: true
rules:
- if: $CI_COMMIT_BRANCH == "main"
- if: $CI_COMMIT_BRANCH == "develop"
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
tags:
- docker
```
## Next Steps
Once you have the basic integration working:
1. **Add More Tests** - Expand your test coverage with proper markers
2. **Set Up Schedules** - Run tests nightly using GitLab's scheduled pipelines
3. **Create Dashboards** - Use QA Sphere reports to track quality trends
4. **Configure Notifications** - Get alerts for test failures
5. **Integrate with Jira** - Link test failures to bug tickets
## Additional Resources
* [QA Sphere CLI Documentation - Playwright Integration](/docs/cli-usage-playwright)
* [QA Sphere CLI Documentation - WebdriverIO Integration](/docs/cli-usage-webdriverio)
* [QA Sphere API Documentation](/docs/api/api_intro)
* [Authentication Guide](/docs/api/authentication)
* [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)
* [Playwright Documentation](https://playwright.dev/)
## Getting Help
If you encounter issues:
1. Check the [Troubleshooting](#troubleshooting) section above
2. Review pipeline logs in GitLab
3. Test CLI locally with same configuration
4. Contact QA Sphere support: [sorted@qasphere.com](mailto:sorted@qasphere.com)
***
**Summary:** You now have everything you need to integrate QA Sphere with GitLab CI/CD. The QAS CLI tool automatically handles test result uploads, making test management seamless and automated. Every pipeline run will now update QA Sphere with the latest test results.
---
# CI/CD Examples
URL: /docs/integrations/ci-cd
Integrate QA Sphere with your continuous integration and deployment pipelines to automatically upload test results after every build.
Each guide provides step-by-step instructions for configuring the QA Sphere CLI tool with your CI/CD platform:
* **[GitHub Actions](https://qasphere.com/docs/integrations/ci-cd/github-actions)** - Automate test result uploads from GitHub Actions workflows
* **[GitLab CI/CD](https://qasphere.com/docs/integrations/ci-cd/gitlab)** - Integrate with GitLab pipelines
* **[Bitbucket Pipelines](https://qasphere.com/docs/integrations/ci-cd/bitbucket)** - Connect Bitbucket Pipelines to QA Sphere
## How It Works
All CI/CD integrations follow the same pattern:
1. Configure your test framework to generate **JUnit XML** reports
2. Add QA Sphere credentials as CI/CD secrets/variables
3. Install the QA Sphere CLI (`qas-cli`) in your pipeline
4. Run `qasphere junit-upload` to send results to QA Sphere
## Prerequisites
Before setting up any integration, ensure you have:
* Tests configured to generate JUnit XML format results
* A QA Sphere account with Test Runner role or higher
* Test cases in QA Sphere with markers (e.g., `BD-001`, `PRJ-123`)
* An API key from QA Sphere Settings
## Quick Reference
| Platform | Secrets Location | Documentation |
| ------------------- | ------------------------------------------ | ---------------------------------- |
| GitHub Actions | Settings → Secrets → Actions | [View Guide](https://qasphere.com/docs/integrations/ci-cd/github-actions) |
| GitLab CI/CD | Settings → CI/CD → Variables | [View Guide](https://qasphere.com/docs/integrations/ci-cd/gitlab) |
| Bitbucket Pipelines | Repository settings → Repository variables | [View Guide](https://qasphere.com/docs/integrations/ci-cd/bitbucket) |
Submitting from inside the app is preferable to email because your workspace and account details come through with the request, so we do not have to ask which instance you are on.
## By Email
You can also reach us directly at [sorted@qasphere.com](mailto:sorted@qasphere.com).
When reporting a problem, these details help us get to an answer faster:
* Your workspace URL (for example `acme.eu1.qasphere.com`)
* What you expected to happen, and what happened instead
* The time the problem occurred, and any error message shown
* A screenshot, if the problem is visible on screen
We aim to respond to all inquiries within 24-48 hours. Response times depend on your plan's support level — see [Billing](/docs/billing).
## New to QA Sphere?
New workspaces show an **onboarding widget** on the main page with guided videos, useful links, and a contact form, which is the fastest way to get oriented. The [Quick Start](/docs/quick-start) guide covers the same ground in writing.
## Before You Write
Some questions have a faster answer than a support ticket:
* **Something changed in the interface?** Check the [Release Notes](/docs/release-notes) — the feature may have moved or been renamed.
* **API or CLI trouble?** The [API Overview](/docs/api/api_intro) covers authentication, rate limits, and error codes, and the [CLI](/docs/cli) page covers installation and auth.
* **Sign-in problems?** [Security](/docs/administration/security) covers sign-in methods and 2FA; [SAML SSO](/docs/saml) has a troubleshooting table keyed by error message.
* **Billing or plan questions?** See [Billing](/docs/billing).
Your feedback is valuable to us and helps improve QA Sphere for everyone.
Thank you for using QA Sphere!
---
# Introduction
URL: /docs
## Welcome to QA Sphere Documentation
This documentation is organized into sections to help you get started quickly and find the information you need.
### Test Management System
Learn the fundamentals of QA Sphere with the [Test Management System](/docs/tms) guide — how to create projects, manage test cases, and execute test runs.
* [Quick Start](/docs/quick-start) - Get up and running in minutes
* [Test Run Configuration](/docs/test-run-configuration) - Configure and manage your test executions
* [Test Plans](/docs/tms/test-plans) - Group related test runs into a release cycle
* [AI Features](/docs/tms/ai-features) - Bulk generation, the test case assistant, duplicate detection, and AI rules
### Integrations
Connect QA Sphere with your favorite tools using [Integrations](/docs/integrations-intro) to streamline bug reporting, defect management, and team notifications.
* Issue trackers: Jira, GitHub Issues, Linear, GitLab, and more
* [Slack](/docs/slack) - Test run and result notifications in your channels
* [MCP Server](/docs/integrations/mcp) - Connect Claude, Cursor, and other AI clients to your test data
* [Webhooks](/docs/webhooks) - Send events to any HTTP endpoint
### Import & Export
Migrate your existing test cases to QA Sphere or export your data with [Import & Export](/docs/import).
* [CSV Import](/docs/import) - Self-service import, plus built-in importers for Qase, Testomat, and Zebrunner
* [Import with AI](/docs/import-with-ai) - Use AI to parse and import existing spreadsheets
* [Export](/docs/export) - Export your test cases and data
### REST API
Build custom integrations using the [QA Sphere REST API](/docs/api/api_intro).
* Authentication, test cases, test runs, results, and more
### CLI
Drive QA Sphere from the terminal with the [CLI](/docs/cli) — install once, then auth, call the API, upload results, and wire up CI/CD.
* [Auth](/docs/cli/auth), [Public API](/docs/cli/public-api), [Result Upload](/docs/integrations/result-upload), [Agent Skill](/docs/cli/agent-skill)
* CI/CD integrations for GitHub Actions, GitLab CI/CD, Bitbucket Pipelines
### Reports
Transform your test data into actionable insights with the Overview dashboard and eight built-in [Reports](/docs/reports-overview).
* View Results, Detailed Results, Run Scorecard, Traceability, Effort by Team Member, and more
### Administration
Configure QA Sphere for your team with [Administration](/docs/administration-intro) — manage users, permissions, security, and billing.
* [Users & Permissions](/docs/users-permissions) - Roles, project access, and suspending users
* [Security](/docs/administration/security) - Sign-in methods, 2FA enforcement, IP allow lists, audit log
* [SAML SSO](/docs/saml) and [SCIM Provisioning](/docs/scim) - Identity provider integration
* [Billing Plans](/docs/billing) - Plans, trial, and subscription management
### Release Notes
Stay up to date with the latest features and improvements in the Release Notes section of the sidebar.
### Help & Support
Get [help and support](/docs/help-and-support) when you need it.
---
# SAML SSO
URL: /docs/saml
QA Sphere supports SAML 2.0 single sign-on, so your team can sign in through identity providers like Okta, Microsoft Entra ID, Auth0, Google Workspace, or JumpCloud instead of managing separate passwords. Combined with [SCIM provisioning](https://qasphere.com/docs/scim), your IdP becomes the single source of truth for who can access QA Sphere.
SAML SSO is available on the **Business plan and above**. Configuration requires the **Admin** or **Owner** role.
## Service Provider Details
QA Sphere does not publish an SP metadata file — register it in your IdP by entering these two values manually. Both are shown with copy buttons in **Settings → Security** once you enable SAML:
| Field | Value |
| ------------------------------- | --------------------------------------------------------------------- |
| **Audience URI (SP Entity ID)** | `urn:hypersequent:qasphere:{workspace-id}` |
| **Single Sign-On URL (ACS)** | `https://{your-company}.{your-region-code}.qasphere.com/api/saml/acs` |
Copy the exact values from the Security page rather than constructing them yourself — the Entity ID embeds your workspace's unique ID.
When configuring the IdP application, keep in mind:
* QA Sphere sends the sign-in request via the **HTTP-Redirect** binding, so your IdP's SAML metadata must advertise an HTTP-Redirect single sign-on endpoint. The response comes back as a standard browser POST to the ACS URL.
* Assertions must be **signed** by the IdP. QA Sphere verifies every response against the certificates in your IdP metadata.
* Do not require **signed AuthnRequests** and do not enable **assertion encryption** — QA Sphere has no SP certificate, so neither is supported.
### Attribute Mapping
QA Sphere resolves the signing-in user by email. Configure your IdP to release:
| Attribute | Purpose |
| --------------------------------------------- | ------------------------------------------------------------- |
| `email` (also accepts `mail`, `emailAddress`) | **Required.** Matched against the QA Sphere account email. |
| `firstName` / `givenName`, `lastName` / `sn` | Optional. Used as the display name when a new user registers. |
| `displayName` or `name` | Optional fallback if first/last name attributes are absent. |
If no email attribute is present, QA Sphere falls back to the NameID — but only when it is an email address. Some IdPs (ADFS in particular) put an opaque identifier in the NameID rather than an email, so always map an explicit email attribute.
## Configuring QA Sphere
1. Go to **Settings → Security** and turn on **Sign in with SAML SSO**.
2. Choose how QA Sphere reads your IdP metadata:
* **Metadata URL** (recommended) — QA Sphere fetches the URL when you save and re-fetches it daily, so IdP certificate rotation is picked up automatically. The URL must be publicly reachable — addresses on private networks are rejected.
* **Metadata XML** — paste the metadata document (or use **Load from file…**), up to 1 MiB. It is used as-is: after your IdP rotates certificates or changes endpoints, you must paste the updated metadata yourself.
3. Copy the **Audience URI** and **Single Sign-On URL** from the same page into your IdP application.
Settings save automatically on change. The metadata is fetched and validated immediately, so mistakes surface right away — for example, metadata without an HTTP-Redirect sign-on endpoint or without a signing certificate is rejected on save.
Once saved, use the **Test SSO login** link on the Security page: it starts the sign-in flow in a new tab, and landing back on the Security page confirms the round trip works.
## How Users Sign In
Members sign in with the **Sign in with SSO** button on your workspace's sign-in page. QA Sphere matches the asserted email against existing accounts and starts a regular session. Multi-factor authentication is your IdP's responsibility — QA Sphere does not run its own 2FA challenge for SAML sign-ins.
New users are not created automatically on first sign-in. Someone must exist in QA Sphere before SAML lets them in:
* **Invite them** from **Settings → Members**. The invitation email opens the registration page, where **Register with SSO** completes sign-up through the IdP. The invitation email must match the email asserted by the IdP.
* **Or provision them via [SCIM](https://qasphere.com/docs/scim)** to automate the whole lifecycle.
Users without an account see an error asking them to request an invitation from an admin.
## Enforcing SSO
To make SAML the only way in, turn off **Password Authentication** and **Sign in with Google** in **Settings → Security** — at least one method must always remain enabled. Disabling a method signs out every user who has no remaining allowed sign-in method.
## Limitations
* Sign-in is SP-initiated only: users start from the QA Sphere sign-in page (or an invitation link), not from the IdP dashboard.
* One IdP configuration per workspace.
* Single Logout (SLO) is not supported — signing out of QA Sphere does not end the IdP session, and vice versa.
* No just-in-time provisioning — use invitations or [SCIM](https://qasphere.com/docs/scim).
The ACS URL contains your workspace subdomain. If your workspace URL changes, update the Single Sign-On URL in your IdP application, or sign-in will break.
## Troubleshooting
| Symptom | Likely cause |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "no HTTP-Redirect SSO Location found in metadata" | Your IdP metadata only advertises an HTTP-POST sign-on endpoint. Enable the HTTP-Redirect binding in the IdP application. |
| "could not fetch SAML metadata from URL" | The metadata URL is unreachable from the internet, returns a non-200 status, or points to a private address. |
| "saml audience mismatch" | The Audience URI in your IdP doesn't match the value shown in **Settings → Security**. |
| "saml assertion invalid" | Signature verification failed — usually stale certificates. Re-save the metadata URL or paste the current metadata XML. |
| "saml assertion expired" | The assertion's validity window doesn't match QA Sphere's clock. Check your IdP's clock settings. With Auth0 this can appear intermittently — retrying usually works. |
| "no account for … ask an admin to invite you" | The user doesn't exist in QA Sphere yet. Invite them or provision via SCIM. |
| "register token email does not match…" | The invitation was sent to a different email than the IdP asserts. Re-invite using the IdP email. |
| "saml login is disabled for this tenant" | The **Sign in with SAML SSO** toggle is off, or your subscription no longer includes advanced authentication. |
If you get stuck, contact [QA Sphere support](https://qasphere.com/docs/help-and-support) with the error message and the time of the failed sign-in attempt — the exact reason a sign-in was rejected is recorded on our side.
---
# SCIM
URL: /docs/scim
QA Sphere supports [SCIM 2.0](https://datatracker.ietf.org/doc/html/rfc7644) (System for Cross-domain Identity Management) so identity providers like Okta, Microsoft Entra ID, and Authentik can automatically provision, update, and deactivate user accounts. Instead of managing users manually in QA Sphere, your IdP keeps them in sync — a new hire is created when assigned, attribute changes are pushed automatically, and a departing employee is deactivated when their access is removed.
## Base URL
```
https://{your-company}.{your-region-code}.qasphere.com/api/scim/v2
```
## Authentication
SCIM uses the same API keys as the rest of QA Sphere. Generate one in **Settings → API Keys** under an account with the **Admin** role. See the [API authentication guide](https://qasphere.com/docs/api/authentication) for details on creating keys.
Configure your identity provider with one of the following `Authorization` header formats — most IdPs default to **Bearer**:
```
Authorization: Bearer {your-api-key}
Authorization: Basic {base64("ApiKey:" + your-api-key)}
```
SCIM requests act on your tenant's user directory. Store the API key in your IdP's secret manager and rotate it like any other production credential.
## Configuring Your Identity Provider
In your IdP's SCIM application, set:
| Field | Value |
| ----------------- | -------------------------------------------------------------------- |
| **SCIM endpoint** | `https://{your-company}.{your-region-code}.qasphere.com/api/scim/v2` |
| **Auth scheme** | Bearer token (or HTTP Basic, depending on the connector) |
| **Token** | Your QA Sphere API key |
Once connected, the IdP can:
* **Create users** by assigning the QA Sphere app to a user or group
* **Update users** when their name or email changes upstream
* **Deactivate users** by unassigning them or disabling them in the IdP
* **Reactivate users** by re-enabling them
## How User Lifecycle Works
### Provisioning
When the IdP creates a user, QA Sphere creates an account with the provided name and email. Passwords are never set via SCIM — the new user sets their initial password through the **Forgot password** flow on the sign-in page.
New users are created with the **User** role and granted access to **all projects** in the workspace. Role and project access changes are not driven by SCIM — adjust them directly in QA Sphere under **Settings → Members**.
### Updating
The IdP can update the user's `name`, `email`, `externalId`, and the `active` flag. Email changes update the user's login email and end any active sessions; the user signs back in with the new address.
### Deactivation and Reactivation
Setting `active: false` **suspends** the user. Their account is preserved along with all historical test cases, runs, results, and audit history they authored — they simply cannot sign in. Setting `active: true` restores access.
QA Sphere does not support hard-deleting users via SCIM. This is intentional: removing a user would orphan the QA history they contributed.
## Supported Attributes
QA Sphere maps a focused subset of the SCIM User schema. Because QA Sphere stores a single name and a single email per user, several SCIM attributes collapse onto the same field:
| SCIM attribute | QA Sphere field |
| ----------------------------------------------------------------------------------------- | ---------------------------- |
| `userName` | Email (also used to sign in) |
| `emails[]` — entry marked `primary: true`, or the first non-empty entry | Email |
| `displayName` (falls back to `name.formatted`, then `name.givenName` + `name.familyName`) | Name |
| `active` | Account enabled |
| `externalId` | IdP correlation ID |
Other attributes in the request payload are accepted but ignored.
## Constraints
A few rules are enforced to keep the directory consistent with QA Sphere's user model:
* **`userName` must be a valid email address.** QA Sphere has no separate username — the email is the identifier used to sign in.
* **`userName` must match the primary email.** If `emails` is included in the payload, its primary value must equal `userName`; otherwise the request is rejected with `400 Bad Request`.
* **Email must be unique across the workspace.** Conflicts return `409 Conflict`.
* **Workspace owners cannot be modified by non-owner callers**, and an owner cannot be deactivated through SCIM. Transfer ownership in QA Sphere first if you need to deprovision an owner.
* **You cannot deactivate the user whose API key is being used.** Use a different admin's key, or have another admin perform the change.
## Auditing
Every SCIM-driven change is recorded in the QA Sphere audit log under **Settings → Audit Log**, including user creation, attribute updates, deactivation, and reactivation. Filter by the SCIM-specific event types to review IdP activity.
## Troubleshooting
| Symptom | Likely cause |
| ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `401 Unauthorized` | API key missing, malformed, or revoked. Re-issue from **Settings → API Keys**. |
| `403 Forbidden` | The API key's owner is not an Admin, or you're trying to modify a workspace owner. |
| `400` "`userName` must be an email address" | Configure your IdP to send the user's email as `userName`. |
| `400` "primary email must match userName" | Map the same value to both `userName` and the email entry in your IdP attribute mapping. |
| `409 Conflict` | A user with that `userName` already exists in QA Sphere. |
If you need help, contact [QA Sphere support](https://qasphere.com/docs/help-and-support) and include the SCIM request and response (with secrets redacted).
---
# Webhooks
URL: /docs/webhooks
Webhooks allow you to receive real-time HTTP notifications when events occur in QA Sphere. When an event triggers, QA Sphere sends an HTTP POST request to your configured endpoint with details about the event.
## Creating a Webhook
Navigate to **Settings > Integrations > Webhooks** and click **Create Webhook**.
### Connection Settings
| Field | Description |
| --------------- | --------------------------------------------------------------- |
| **Name** | A descriptive name for your webhook |
| **Endpoint** | The HTTPS URL where webhook payloads will be sent |
| **Secret** | Optional shared secret for signature verification (recommended) |
| **Event Types** | Select which events should trigger this webhook |
| **Enabled** | Toggle to enable or disable the webhook |
### Request Customization
You can customize the HTTP request sent to your endpoint:
* **Headers**: Add custom headers (one per line, format: `Header-Name: value`)
* **Payload**: Define a custom JSON payload template with variable substitution
### Project Permissions
Control which projects trigger the webhook:
* **All Projects**: Webhook fires for events in any project
* **Specific Projects**: Select individual projects to monitor
## Event Types
| Event | Description |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| `plan_created` | A test plan was created |
| `plan_updated` | A test plan was updated, closed, reopened, or deleted |
| `run_created` | A test run was created |
| `run_updated` | A test run was updated, closed, reopened, or deleted |
| `tcase_created` | A single test case was created |
| `tcases_created` | Multiple test cases were created in a batch operation (e.g. copy multiple, Bulk AI generation) |
| `tcase_edited` | A single test case was edited |
| `tcases_edited` | Multiple test cases were edited in a batch operation |
| `result_created` | A single test result was recorded |
| `results_created` | Multiple test results were recorded in a batch operation |
## Template Variables
Use template variables in your custom payload and headers using the `${variable}` syntax.
### Universal Variables
Available for all event types:
| Variable | Type | Description |
| ------------------- | ------- | ---------------------------------------------------- |
| `${event_type}` | string | The event type (e.g., `plan_created`, `run_updated`) |
| `${timestamp}` | string | RFC3339 timestamp when the event occurred |
| `${project_id}` | string | The project's unique identifier |
| `${project_code}` | string | The project's short code (e.g., `PRJ`) |
| `${id}` | string | The entity's unique identifier |
| `${name}` | string | The entity's title or name |
| `${url}` | string | Direct URL to view the entity in QA Sphere |
| `${event_creator}` | string | Name of the user who performed the action |
| `${event_created}` | string | RFC3339 timestamp when the action occurred |
| `${entity_creator}` | string | Name of the user who originally created the entity |
| `${entity_created}` | string | RFC3339 timestamp when the entity was created |
| `${is_deleted}` | boolean | Whether the entity is deleted (`true` or `false`) |
### Plan-Specific Variables
| Variable | Type | Description |
| ---------------------- | ------ | ---------------------------------------------------------- |
| `${event_description}` | string | Description of the action (e.g., "Plan created") |
| `${configuration}` | string | Comma-separated list of configuration names |
| `${completed_on}` | string | RFC3339 timestamp when the plan was closed (empty if open) |
### Run-Specific Variables
| Variable | Type | Description |
| ---------------------- | ------ | --------------------------------------------------------- |
| `${event_description}` | string | Description of the action (e.g., "Run created") |
| `${assigned_to}` | string | Name of the assigned user (empty if unassigned) |
| `${configuration}` | string | Configuration name (empty if none) |
| `${completed_on}` | string | RFC3339 timestamp when the run was closed (empty if open) |
### Test Case-Specific Variables
| Variable | Type | Description |
| ------------------- | ------ | ---------------------------------------- |
| `${tcase_seq}` | string | Test case sequence number |
| `${tcase_priority}` | string | Priority level (`low`, `medium`, `high`) |
### Result-Specific Variables
| Variable | Type | Description |
| ---------------------- | ------ | ------------------------------------------------------------------ |
| `${event_description}` | string | Description including test case and run titles |
| `${result_status}` | string | Result status (e.g., `passed`, `failed`, `skipped`, `blocked`) |
| `${result_comment}` | string | Comment added to the result (empty string if no comment was added) |
| `${result_links}` | string | Comma-separated list of link URLs (empty if no links) |
### Bulk Event Variables
For `results_created` events:
| Variable | Type | Description |
| ---------- | ----- | ---------------------------------------------- |
| `${ids}` | array | Array of result IDs (when used as exact value) |
| `${items}` | array | Array of item objects with individual details |
Each item in `${items}` contains:
* `id` - Result ID
* `url` - URL to view the result
* `result_status` - Result status (e.g., `passed`, `failed`)
* `result_comment` - Comment added to the result
* `result_links` - Comma-separated list of link URLs
## Payload Examples
### Default Payload
When no custom payload is specified, QA Sphere sends:
```json
{
"event_type": "run_created",
"timestamp": "2026-01-21T11:07:57Z",
"data": {
"id": "22",
"name": "UI Testing Test Run",
"url": "https://example.qasphere.com/project/DB/run/22",
"project_id": "1CJjW1Amf_a8hximyr325zz",
"project_code": "DB",
"event_description": "Run created",
"event_creator": "Nick Lapis-Trout",
"event_created": "2026-01-21T11:07:57Z",
"entity_creator": "Nick Lapis-Trout",
"entity_created": "2026-01-21T11:07:57Z",
"is_deleted": false,
"assigned_to": "Nick Lapis-Trout",
"configuration": "Android",
"completed_on": ""
}
}
```
### Custom Payload with Variables
```json
{
"event": "${event_type}",
"project": "${project_code}",
"entity": {
"id": "${id}",
"name": "${name}",
"url": "${url}"
},
"actor": "${event_creator}",
"deleted": "${is_deleted}"
}
```
### Typed Variable Substitution
When a variable is the **exact and only value** of a JSON field, it preserves its type:
```json
{
"deleted": "${is_deleted}",
"result_ids": "${ids}"
}
```
Results in:
```json
{
"deleted": true,
"result_ids": ["123", "456", "789"]
}
```
When a variable is **embedded in a string**, it becomes a string:
```json
{
"message": "Entity ${id} was ${event_type}"
}
```
Results in:
```json
{
"message": "Entity 42 was run_created"
}
```
## Integration Examples
### Slack
QA Sphere also offers a native [Slack integration](/docs/slack) with ready-made notifications, slash commands, and link previews — no webhook configuration needed. Use a webhook only if you need full control over the message format.
To send webhook notifications to Slack, create a [Slack Incoming Webhook](https://api.slack.com/messaging/webhooks) and use it as your endpoint. Configure a custom payload using Slack's Block Kit format:
**Event Types**: Select `tcase_created` to notify when new test cases are added.
**Custom Payload**:
```json
{
"text": "${event_creator} created a new test case in ${project_code}",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*${event_creator}* created a new test case:"
}
},
{
"type": "divider"
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*<${url}|${name}>*\nProject: ${project_code}\nPriority: ${tcase_priority}"
}
}
]
}
```
This produces a Slack message like:
> **John Doe** created a new test case:
>
> ***
>
> **[Verify login with valid credentials](https://example.qasphere.com/project/PRJ/tcase/42)**
> Project: PRJ
> Priority: high
The `text` field serves as a fallback for notifications and accessibility. Always include it alongside `blocks`.
## Request Headers
QA Sphere automatically includes these headers with every webhook request:
| Header | Description |
| --------------------- | ----------------------------------------------------- |
| `Content-Type` | Always `application/json` |
| `X-Webhook-ID` | Unique identifier for this delivery (for idempotency) |
| `X-Webhook-Timestamp` | Unix timestamp when the request was sent |
| `X-Webhook-Signature` | HMAC-SHA256 signature (only if secret is configured) |
### Custom Headers
Add custom headers in the webhook configuration:
```
Authorization: Bearer your-token
X-Custom-Header: custom-value
X-Project: ${project_code}
```
**Reserved Headers**
The following headers cannot be overridden: `X-Webhook-Timestamp`, `X-Webhook-Signature`, `X-Webhook-ID`, `Host`, and proxy-related headers.
## Signature Verification
When a secret is configured, QA Sphere signs the payload using HMAC-SHA256. **We strongly recommend verifying signatures** to ensure requests originate from QA Sphere.
### Signature Format
The signature is provided in the `X-Webhook-Signature` header:
```
sha256=
### Viewers Do Not Consume Seats
On paid plans, **Viewer** accounts are unlimited and free. Product managers, developers, and other stakeholders who only need to follow quality status can be added without affecting your bill. Only roles above Viewer count toward the per-user price.
On free accounts the paid-seat and viewer distinction does not apply; the overall user limit governs instead.
See [Users and Permissions](https://qasphere.com/docs/users-permissions) for what each role can do.
## Choosing the Right Plan
When selecting a plan, consider the following factors:
1. **Team Size**: How many active users will need access to QA Sphere? Remember that viewers are unlimited and free.
2. **Project Complexity**: Do you manage multiple projects or have complex testing requirements?
3. **Storage Needs**: How much documentation and test artifact storage do you require?
4. **AI Usage**: How heavily will you use AI generation and the AI assistant? See [AI Features](/docs/tms/ai-features) for what consumes credits.
5. **Security Requirements**: Do you need SAML SSO, SCIM provisioning, 2FA enforcement, or an IP allow list? Those are Business-tier features.
6. **Support Level**: What level of support does your team need to operate efficiently?
Remember, you can start with the Free tier to explore QA Sphere's capabilities and upgrade as your needs grow. Our flexible structure ensures that you're never locked into a plan that doesn't serve your current needs.
---
# Security
URL: /docs/administration/security
Workspace-wide security is configured in **Settings → Security**. This page covers the controls available there and how they interact. Configuring them requires the **Admin** or **Owner** role.
## Sign-In Methods
QA Sphere supports several ways in, and you choose which are enabled for your workspace:
| Method | Availability | Notes |
| ------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| **Password** | All plans | Email and password, with optional two-factor authentication |
| **Google Sign-In** | All paid plans | Can be restricted to approved email domains |
| **SAML 2.0 SSO** | Business plan and above | Okta, Microsoft Entra ID, Auth0, Google Workspace, JumpCloud, and others — see [SAML SSO](/docs/saml) |
At least one sign-in method must remain enabled at all times. Disabling a method signs out every user who has no remaining allowed method, so check who depends on a method before turning it off.
To make SSO the only way in, turn off both **Password Authentication** and **Sign in with Google** once SAML is verified.
### Restricting Google Sign-In to Your Domains
Google Sign-In accepts any Google account by default. Add an allowlist of approved email domains to limit it to accounts you control, so a personal Gmail address cannot be used to reach an invited seat. The allowlist is part of the Google Sign-In configuration, so it is available wherever Google Sign-In is.
If your organization uses several verified domains, list all of them. Users whose Google account falls outside the allowlist are rejected at sign-in.
## Two-Factor Authentication
Two-factor authentication is available on **every plan**, and any user can enable it for their own account from their profile.
### Enforcing 2FA Workspace-Wide
On the **Business plan**, admins can require 2FA for everyone in the workspace. When you enable enforcement:
* Users who already have 2FA configured are unaffected.
* Users without 2FA are signed out and must complete 2FA setup on their next sign-in.
Enforcement signs out every user who has not yet set up 2FA. Announce it before you enable it, or you will field a wave of confused messages from people who cannot get back in.
The 2FA status of each member is visible and sortable in **Settings → Members**, which is the quickest way to see who still needs to enrol before you enforce.
2FA applies to password sign-ins. For SAML sign-ins, multi-factor authentication is your identity provider's responsibility — QA Sphere does not run its own challenge on top of a SAML assertion.
## IP Allow List
On the **Business plan**, workspace access can be restricted to a list of approved IP addresses or CIDR ranges — useful when access should only be possible from an office network or a corporate VPN.
Before enabling it, work through the list of everything that reaches your workspace:
* **Your own current address**, or you will lock yourself out along with everyone else
* **Remote and travelling team members**, whose addresses change
* **CI/CD runners** that upload results through the [CLI](/docs/cli) or call the [public API](/docs/api/api_intro) — cloud runners often use wide, changing ranges
* **Webhook and integration callbacks**, if they originate from your own infrastructure
Before switching the allow list on, confirm whether it also covers API and CLI traffic in your configuration. If it does, a pipeline that uploads test results will start failing as soon as its runner's egress addresses fall outside the list. Test it against a non-critical pipeline first.
## Managing User Access
### Suspending and Restoring Users
Admins can **suspend** a user instead of deleting them. A suspended user cannot sign in, but their account and everything they authored — test cases, runs, results, audit history — is preserved intact. Restoring access is a single action.
Suspend rather than delete when someone leaves a team temporarily, when an account may be compromised, or when you want to free a seat without losing attribution. See [Users and Permissions](https://qasphere.com/docs/users-permissions) for roles and project access.
API keys owned by a suspended user stop working: requests made with them return `403`. If a departing user's key is used by a pipeline, reissue the key under a different account before suspending them.
### Automated Provisioning
On the Business plan, [SCIM 2.0](/docs/scim) lets your identity provider create, update, and deactivate QA Sphere users automatically. Setting `active: false` from the IdP suspends the user in the same way as the manual action above; `active: true` restores them.
## Audit Log
Every significant action in the workspace is recorded in the audit log, viewable under **Settings → Audit Log**. It covers user and permission changes, integration and webhook configuration changes, SCIM-driven changes, and **rejected authentication attempts**, which can be filtered specifically when investigating suspicious sign-in activity.
For SIEM ingestion, the audit log is available through the public API, and you can create API keys restricted to only that endpoint by naming them with the `SIEM-LOG-ONLY` prefix — a key named `SIEM-LOG-ONLY-splunk` can read audit logs and nothing else. See the [Audit Logs API](/docs/api/audit_logs).
## What Each Plan Includes
| Control | Free | Standard | Business | Enterprise |
| ----------------------------------------------------------------------------------- | ----- | -------- | -------- | ---------- |
| Two-factor authentication (per user) | Yes | Yes | Yes | Yes |
| Google Sign-In (and its domain allowlist) | — | Yes | Yes | Yes |
| SAML 2.0 SSO | — | — | Yes | Yes |
| SCIM provisioning | — | — | Yes | Yes |
| Audit log | Basic | Basic | Extended | Extended |
| **Advanced authentication**: 2FA enforcement, IP allow list, audit log API for SIEM | — | — | Yes | Yes |
See [Billing](https://qasphere.com/docs/billing) for full plan details.
---
# Users and Permissions
URL: /docs/users-permissions
Effective user management and role-based access control are crucial for maintaining security and efficiency in your QA processes. QA Sphere offers a flexible and robust permissions system that allows you to fine-tune access levels for each member of your team. This guide will walk you through the various roles available in QA Sphere and how to manage them.
## Understanding QA Sphere Roles
QA Sphere provides five distinct roles, each with its own set of permissions and responsibilities. These roles are designed to cater to different levels of involvement and authority within your QA process.
### 1. Owner
The Owner role is the highest level of authority in QA Sphere.
**Key Characteristics:**
* There can only be one Owner per QA Sphere instance.
* The Owner is typically the first user who set up the QA Sphere account.
* This role cannot be deleted.
**Permissions:**
* Has unrestricted access to all features and settings.
* Can change anything within the system.
* Can assign the Owner role to another user (in which case, the current Owner becomes an Admin).
**Best Practices:**
* Reserve this role for the highest level of management or the primary stakeholder of the QA process.
* Consider transitioning to an Admin role once the system is set up and stable, to reduce the risk of accidental system-wide changes.
### 2. Admin
The Admin role is designed for users who need comprehensive control over the QA Sphere instance, but with some limitations compared to the Owner.
**Permissions:**
* Can change almost anything in the system.
* Has access to all projects and global settings.
* Can manage users, including creating new users and assigning roles.
* Cannot delete the Owner or change the Owner's permissions.
**Best Practices:**
* Assign this role to QA managers or team leads who need to oversee multiple projects and manage team members.
* Limit the number of Admins to maintain better control and security.
### 3. User
The User role is suitable for team members actively involved in the QA process across one or more projects.
**Permissions:**
* Can work on specific projects or all projects (as assigned by an Admin or Owner).
* Can create and manage test runs, milestones, and test cases within their assigned projects.
* Cannot add new projects, rename/complete/delete projects, manage users, or change global settings.
**Best Practices:**
* This should be the default role for most team members involved in creating and executing tests.
* Regularly review User project assignments to ensure they have access to all necessary projects.
### 4. Test Runner
The Test Runner role is designed for team members primarily responsible for executing test runs.
**Permissions:**
* Can work on test runs of specific projects (or all projects, as assigned).
* Can update test run status and results.
* Cannot modify test cases or create new ones.
* Cannot change project settings or manage users.
**Best Practices:**
* Assign this role to team members focused on test execution, such as QA testers or automated testing systems.
* Ensure Test Runners have clear guidelines on how to report and document test results.
### 5. Viewer
The Viewer role provides read-only access to QA Sphere, suitable for stakeholders who need to monitor progress but should not make changes.
**Permissions:**
* Can view information in specific projects or all projects (as assigned).
* All access is read-only; cannot make any changes to test cases, runs, or settings.
**Best Practices:**
* Use this role for external stakeholders, clients, or team members who need to stay informed but are not directly involved in the QA process.
* Regularly review Viewer access to ensure they only have visibility to relevant projects.
Viewer seats are **unlimited and free** on paid plans. Stakeholders who only need to follow quality status should be Viewers — they do not count toward your per-user bill. See [Billing](https://qasphere.com/docs/billing#viewers-do-not-consume-seats).
## Project Access
A role decides *what* a user can do; project access decides *where* they can do it. Users, Test Runners, and Viewers are granted access either to **all projects** or to a specific set of projects, chosen when you invite them and changeable at any time from **Settings → Members**.
Owners and Admins always have access to every project, so project access does not apply to them.
The **Access** column in the Members table shows each user's current scope, and the table can be sorted by it — useful when reviewing who can reach a sensitive project.
## Managing Users and Permissions
As an Owner or Admin, you have the responsibility of managing users and their permissions. Here's how to effectively manage your team in QA Sphere:
1. **Adding New Users:**
* Navigate to the **Settings** 
> **Members**.
* Use **Email** field to invite new users to the team
* Assign the appropriate role and project access and click **Send Invite**.
2. **Modifying User Roles:**
* Navigate to the **Settings** 
* Change **Role** in the appropriate field
3. **Reviewing the Member List:**
* The Members table can be sorted by Name/Email, Role, 2FA, and Access. Sorting cycles ascending → descending → reset, and the indicators stay visible.
* Sorting by **2FA** is the quickest way to see who has not yet enrolled, which matters before you [enforce two-factor authentication](https://qasphere.com/docs/administration/security#enforcing-2fa-workspace-wide).
4. **Best Practices for User Management:**
* Regularly audit user roles and permissions to ensure they align with current responsibilities.
* Implement a process for reviewing and updating permissions when team members change roles.
* Use groups to manage permissions for multiple users with similar roles more efficiently.
* Always follow the principle of least privilege: give users only the permissions they need to perform their tasks.
## Suspending and Restoring Access
When someone should lose access but their history should be kept, **suspend** them instead of deleting the account. A suspended user cannot sign in, while everything they authored — test cases, runs, results, and audit history — stays intact and correctly attributed. Restoring access is a single action.