You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Add public API commands
* Move SKILL.md
* Update @filename description
* Fixes
* Prevent accidental leaks
* Run npm audit fix
* Better error message
* Tweaks
* Fix live tests
* Indicate HTML support on fields
* Fix uri encoding
* Validate path parameters
* Simplify test
* Rename APIs
* Add two-layer API validation and custom fields support
- Add Zod schemas at API level for all request types with validateRequest()
that throws RequestValidationError, caught by apiHandler for clean error output
- Add handleValidationError() + buildArgumentMap() to map API field names to
CLI argument names (e.g., title → --title) for user-friendly error messages
- Move validation schemas from command-level to API-level as single source of
truth; command handlers pass args directly to API functions
- Add customFields, parameterValues, and filledTCaseTitleSuffixParams to
test-case create/update commands with proper validation (parameterValues
restricted to template type)
- Fix jsonResponse null crash, expand ResultStatus with custom statuses,
relax test-cases update check, extract shared superRefine for run schemas
- Add tests for new fields (mocked + live) and batch-create validation errors
* Use ZodError.message as the error message
* Fix schemas
* Remove schemas.ts and update claude.md
* Simplify SKILL.md
* Create specific validtors for different types of identifiers
* Fix step schema
* Fix types and --include argument
* Address feedback
* Fix mock test
* More fixes
* Fix name
* Fix table of contents
* Rewrite to manifest based pattern
* Update md files
* Fixes
* Fixes
* Fix common help text usage
* Fix error code on unknown arguments, fix live test arguments
* Fix spy restore
* Fixes
* Improve SKILL.md
* Align file upload docs and tests with batch endpoint
---------
Co-authored-by: Satvik Choudhary <satvikchoudhary@gmail.com>
-`src/bin/qasphere.ts` — Entry point (`#!/usr/bin/env node`). Validates Node version, delegates to `run()`.
32
-
-`src/commands/main.ts` — Yargs setup. Registers three commands (`junit-upload`, `playwright-json-upload`, `allure-upload`) as instances of the same `ResultUploadCommandModule` class.
32
+
-`src/commands/main.ts` — Yargs setup. Registers three upload commands (`junit-upload`, `playwright-json-upload`, `allure-upload`) as instances of `ResultUploadCommandModule`, plus the `api` command.
33
33
-`src/commands/resultUpload.ts` — `ResultUploadCommandModule` defines CLI options shared by both commands. Loads env vars, then delegates to `ResultUploadCommandHandler`.
@@ -62,24 +62,52 @@ The upload flow has two stages handled by two classes, with a shared `MarkerPars
62
62
-`allureParser.ts` — Parses Allure JSON results directories (`*-result.json` and `*-container.json` files; XML/images ignored). Supports test case linking via TMS links (`type: "tms"`) or marker in test name, maps Allure statuses to QA Sphere result statuses (`unknown→open`, `broken→blocked`), strips ANSI codes and HTML-escapes messages, and resolves attachments via `attachments[].source`. Uses `formatMarker()` from `MarkerParser`. Extracts run-level failure logs from container files by checking `befores`/`afters` fixtures with `failed`/`broken` status — primarily useful for pytest (allure-junit5 and allure-playwright leave container fixtures empty).
63
63
-`types.ts` — Shared `TestCaseResult`, `ParseResult`, and `Attachment` interfaces used by both parsers.
64
64
65
+
### API Command (src/commands/api/)
66
+
67
+
The `api` command provides direct programmatic access to the QA Sphere public API: `qasphere api <resource> <action> [options]`. Each resource (e.g., `projects`, `runs`, `test-cases`) is a subcommand with its own actions. Some resources have nested subgroups (e.g., `qasphere api runs test-cases list`).
68
+
69
+
**Architecture**: The API command uses a manifest-based pattern. Each resource defines its endpoints as declarative `ApiEndpointSpec` objects (in `src/commands/api/manifests/`), and shared infrastructure handles yargs registration, validation, and execution.
70
+
71
+
**Key files**:
72
+
73
+
-`types.ts` — Defines `ApiEndpointSpec` as a discriminated union on `bodyMode` (`'none'` | `'json'` | `'file'`), plus supporting types (`ApiPathParamSpec`, `ApiFieldSpec`, `ApiQueryOptionSpec`, `ExecuteFn`)
74
+
-`manifests/` — One file per resource (e.g., `runs.ts`, `test-cases.ts`), each exporting an array of `ApiEndpointSpec` objects. `manifests/index.ts` aggregates all specs into a single `allSpecs` array. `manifests/utils.ts` has shared param definitions (e.g., `projectCodeParam`)
75
+
-`builder.ts` — `buildCommandsFromSpecs()` builds a yargs command tree from the flat specs array, handling nested command paths automatically. Creates yargs options from path params, query options, field options, and body mode
76
+
-`executor.ts` — `executeCommand()` orchestrates execution: collects and validates path params → processes body (based on `bodyMode` discriminant) → collects and validates query options → connects to API (lazy env loading) → executes with error mapping
77
+
-`main.ts` — Registers the `api` command, delegates to `buildCommandsFromSpecs()`
78
+
-`utils.ts` — Shared helpers: `printJson()`, `apiDocsEpilog()`, `formatApiError()`, `ArgumentValidationError`, `kebabToCamelCase()`, body parsing (`parseBodyInput`, `mergeBodyWithFields`), validation (`validateFieldValues`, `validateOptionValues`), collection helpers (`collectFieldValues`, `collectPathParamValues`, `collectQueryValues`), and `handleApiValidationError()` for reformatting API errors into CLI argument names
79
+
80
+
Important note: Online documentation is available at https://docs.qasphere.com. Most leaf pages have a markdown version available by appending `.md` in the URL. Use the markdown version before falling back to the original URL if the markdown version returns >= 400 status.
81
+
82
+
**Key design patterns**:
83
+
84
+
-**Manifest-based declarations**: Each endpoint is a plain object (`ApiEndpointSpec`) declaring its command path, params, options, body mode, and execute function. The builder and executor handle all yargs wiring, validation, and error handling generically
85
+
-**Lazy env loading**: `QAS_URL`/`QAS_TOKEN` are loaded only when the API is actually called (inside `executeCommand()`), so CLI validation errors are reported first
86
+
-**Validation flow**: Path params and query options are validated against optional Zod schemas. For `json` body mode, individual field values are validated (with JSON parsing for complex fields), then merged with `--body`/`--body-file` input. API-level `RequestValidationError` is caught and reformatted into CLI argument names (e.g., `--query-plans: [0].tcaseIds: not allowed for "live" runs`)
87
+
65
88
### API Layer (src/api/)
66
89
67
90
Composable fetch wrappers using higher-order functions:
68
91
69
-
-`utils.ts` — `withBaseUrl`, `withApiKey`, `withJson` decorators that wrap `fetch`
70
-
-`index.ts` — `createApi(baseUrl, apiKey)` assembles the API client from sub-modules
-`utils.ts` — `withBaseUrl`, `withApiKey`, `withJson`, `withDevAuth` decorators that wrap `fetch`; `jsonResponse<T>()` for parsing responses; `appendSearchParams()` for building query strings; `resourceIdSchema` for validating resource identifiers; `printJson()` for formatted JSON output
93
+
-`index.ts` — `createApi(baseUrl, apiKey)` assembles the API client from all sub-modules
94
+
-`schemas.ts` — Shared types (`ResourceId`, `ResultStatus`, `PaginatedResponse<T>`, `PaginatedRequest`, `MessageResponse`), `RequestValidationError` class, `validateRequest()` helper, and common Zod field definitions (`sortFieldParam`, `sortOrderParam`, `pageParam`, `limitParam`)
95
+
- One sub-module per resource (e.g., `projects.ts`, `runs.ts`, `tcases.ts`, `folders.ts`), each exporting a `create<Resource>Api(fetcher)` factory function. Each module defines Zod schemas for its request types (PascalCase, e.g., `CreateRunRequestSchema`), derives TypeScript types via `z.infer`, and validates inputs with `validateRequest()` inside API functions
96
+
97
+
The main `createApi()` composes the fetch chain: `withDevAuth(withApiKey(withBaseUrl(fetch, baseUrl), apiKey))`.
72
98
73
99
### Configuration (src/utils/)
74
100
75
-
-`env.ts` — Loads `QAS_TOKEN` and `QAS_URL` from environment variables, `.env`, or `.qaspherecli` (searched up the directory tree)
101
+
-`env.ts` — Loads `QAS_TOKEN` and `QAS_URL` from environment variables, `.env`, or `.qaspherecli` (searched up the directory tree). Optional `QAS_DEV_AUTH` adds a dev cookie via the `withDevAuth` fetch decorator
76
102
-`config.ts` — Constants (required Node version)
77
103
-`misc.ts` — URL parsing, template string processing (`{env:VAR}`, date placeholders), error handling utilities. Note: marker-related functions have been moved to `MarkerParser.ts`
78
104
-`version.ts` — Reads version from `package.json` by traversing parent directories
79
105
80
106
## Testing
81
107
82
-
Tests use **Vitest** with **MSW** (Mock Service Worker) for API mocking. Test files are in `src/tests/`:
108
+
Tests use **Vitest** with **MSW** (Mock Service Worker) for API mocking. Test files are in `src/tests/`.
109
+
110
+
### Upload Command Tests
83
111
84
112
-`result-upload.spec.ts` — Integration tests for the full upload flow (JUnit, Playwright, and Allure), with MSW intercepting all API calls. Includes hyphenless and CamelCase marker tests (JUnit only)
85
113
-`marker-parser.spec.ts` — Unit tests for `MarkerParser` (detection, extraction, matching across all marker formats and command types)
@@ -90,6 +118,51 @@ Tests use **Vitest** with **MSW** (Mock Service Worker) for API mocking. Test fi
90
118
91
119
Test fixtures live in `src/tests/fixtures/` (XML files, JSON files, and mock test case data).
92
120
121
+
### API Command Tests (src/tests/api/)
122
+
123
+
Tests for the `api` command are organized by resource under `src/tests/api/`, with one spec file per action (e.g., `projects/list.spec.ts`, `runs/create.spec.ts`). Tests support both mocked and live modes.
-`baseURL`, `token` — Configured base URL and token (mocked values or real from env vars)
128
+
-`useMockServer(...handlers)` — Sets up MSW server with lifecycle hooks (before/after each test)
129
+
-`runCli(...args)` — Invokes the CLI programmatically via `run(args)`, captures and parses JSON output. Useful only if the command prints JSON.
130
+
-`test` fixture — Extended Vitest `test` that provides a `project` fixture (mock project in mocked mode, real project with cleanup in live mode)
131
+
-`expectValidationError(runner, pattern)` — Asserts a command exits with a validation error matching the given regex
132
+
- Helper functions for live tests: `createFolder()`, `createTCase()`, `createRun()`
133
+
134
+
**Global setup** (`src/tests/global-setup.ts`): Authenticates against the live API (if env vars are set) and provides a session token for test project cleanup.
135
+
136
+
**Test pattern**: Each spec file typically contains:
137
+
138
+
1. A `describe('mocked', ...)` block with MSW handlers and assertions on request headers/params
The QAS CLI is a command-line tool for submitting your test automation results to [QA Sphere](https://qasphere.com/). It provides the most efficient way to collect and report test results from your test automation workflow, CI/CD pipeline, and build servers.
The `junit-upload`, `playwright-json-upload`, and `allure-upload` commands upload test results to QA Sphere.
@@ -272,6 +377,16 @@ The CLI automatically detects global or suite-level failures and uploads them as
272
377
- **Playwright JSON**: Top-level `errors` array entries (global setup/teardown failures) are extracted as run-level logs.
273
378
- **Allure**: Failed or broken `befores`/`afters` fixtures in `*-container.json` files (e.g., session/module-level setup/teardown failures from pytest) are extracted as run-level logs.
274
379
380
+
## AI Agent Skill
381
+
382
+
qas-cli includes a [SKILL.md](./SKILL.md) file that enables AI coding agents (e.g., Claude Code, Cursor) to use the CLI effectively. To add this skill to your agent:
383
+
384
+
```bash
385
+
npx skills add Hypersequent/qas-cli
386
+
```
387
+
388
+
The skill provides the agent with full documentation of the CLI commands, options, and conventions. See [skills](https://github.com/vercel-labs/skills) for more details.
389
+
275
390
## Development (for those who want to contribute to the tool)
276
391
277
392
1. Install and build: `npm install && npm run build && npm link`
0 commit comments