@powerduck/openapi-cli 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +110 -227
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,17 +1,25 @@
1
1
  # @powerduck/openapi-cli
2
2
 
3
- CI-ready command-line tool for batch-testing OpenAPI 3.2 documents across six protocols. Runs every operation in your spec, runs assertions against each response, and produces JSON, CLI, and HTML reports.
4
-
5
3
  [![npm version](https://img.shields.io/npm/v/@powerduck/openapi-cli)](https://www.npmjs.com/package/@powerduck/openapi-cli)
6
4
  [![license](https://img.shields.io/npm/l/@powerduck/openapi-cli)](https://github.com/PowerDuckie/openapi-cli/blob/main/LICENSE)
5
+ [![downloads](https://img.shields.io/npm/dm/@powerduck/openapi-cli)](https://www.npmjs.com/package/@powerduck/openapi-cli)
7
6
 
8
- ## Links
7
+ CI-ready command-line tool for batch-testing OpenAPI 3.2 documents across six protocols. Runs every operation in your spec, runs assertions against each response, and produces JSON, CLI, and HTML reports.
9
8
 
10
- - [Official Website](https://www.powerduck.com/opensource/openapi-cli.html)
11
- - [Documentation](https://www.powerduck.com/docs/openapi-cli/introduction)
12
- - [Live Demo](https://www.powerduck.com/demo/openapi-cli.html)
13
- - [GitHub](https://github.com/PowerDuckie/openapi-cli)
14
- - [npm](https://www.npmjs.com/package/@powerduck/openapi-cli)
9
+ ---
10
+
11
+ Powerduck is an open-source developer tooling platform for teams building modern API workflows.
12
+
13
+ - **6 Protocols** — HTTP/1.1, HTTP/2, HTTP/3, WebSocket, SSE, and gRPC
14
+ - **Batch Testing** — Run every operation in your OpenAPI spec concurrently
15
+ - **Assertion Engine** — Validate status codes, headers, response bodies, and schemas
16
+ - **3 Report Formats** — JSON for CI, CLI for terminal, HTML for dashboards
17
+ - **Authentication** — Bearer tokens, API keys, Basic auth, OAuth2, and custom headers
18
+ - **Filtering** — Run tests by tag, path, method, operationId, or regex
19
+ - **Concurrency Control** — Configurable parallelism with rate limiting
20
+ - **gRPC Reflection** — Auto-discover gRPC services via server reflection
21
+ - **MCP Integration** — Streamable HTTP and stdio MCP transport support
22
+ - **GitHub Actions** — First-class CI integration with annotations and summaries
15
23
 
16
24
  ---
17
25
 
@@ -32,7 +40,12 @@ openapi-cli --spec openapi.json --server https://api.example.com
32
40
  ### Programmatic usage
33
41
 
34
42
  ```typescript
35
- import { resolveConfig, runTests, generateJsonReport, generateHtmlReport } from "@powerduck/openapi-cli";
43
+ import {
44
+ resolveConfig,
45
+ runTests,
46
+ generateJsonReport,
47
+ generateHtmlReport,
48
+ } from "@powerduck/openapi-cli";
36
49
 
37
50
  const config = resolveConfig({
38
51
  spec: "./openapi.json",
@@ -78,269 +91,139 @@ jobs:
78
91
 
79
92
  ---
80
93
 
81
- ## Features
82
-
83
- - **CI-ready** — non-zero exit code on test failure, drops straight into GitHub Actions, GitLab CI, or any pipeline
84
- - **Six protocols** — HTTP, SSE, WebSocket, GraphQL, gRPC, and MCP operations in one spec, one runner
85
- - **Two assertion styles** — declarative `x-tests` arrays for simple checks, and full Postman `pm.test()` / `pm.expect()` scripts for complex ones
86
- - **Three report formats** — machine-readable JSON, colored human-readable CLI output, and self-contained interactive HTML
87
- - **Local or remote specs** — load from a file path or an `http(s)://` URL with redirect following and timeout enforcement
88
- - **Flexible filtering** — run a subset of operations by method, path, tag, or operationId
89
- - **Bounded concurrency** — configurable max concurrent requests with per-request timeout
90
- - **Authentication** — Bearer token, Basic auth, API key (header/query), with environment variable expansion
91
- - **Proxy support** — HTTP(S) proxy URL for corporate networks
92
- - **TLS configuration** — CA cert, client cert/key, and insecure mode for self-signed certs
93
- - **Built on `@powerduck/openapi-request`** — full OpenAPI parameter serialization (path/query/header/cookie styles and explode rules)
94
- - **Dual ESM/CJS builds** — works with `import` and `require`
95
-
96
- ---
97
-
98
- ## CLI Usage
99
-
100
- ```
101
- openapi-cli [options]
94
+ ## Links
102
95
 
103
- Options:
104
- --spec <path> Path or URL to OpenAPI 3.2 spec (required)
105
- --server <url> Override server base URL from spec
106
- --output <dir> Output directory for reports (default: ./openapi-cli-report)
107
- --format <formats> Comma-separated report formats: json,cli,html (default: json,cli,html)
108
- --concurrency <n> Max concurrent requests (default: 5)
109
- --timeout <ms> Per-request timeout in ms (default: 30000)
110
- --filter-method <m> Filter by HTTP method (comma-separated)
111
- --filter-path <regex> Filter by path regex
112
- --filter-tag <tag> Filter by tag (comma-separated)
113
- --filter-operation <id> Filter by operationId (comma-separated)
114
- --bearer <token> Bearer token for Authorization header
115
- --basic <user:pass> Basic auth credentials
116
- --apikey <key=value> API key (name=value), use --apikey-in to set location
117
- --apikey-in <location> API key location: header or query (default: header)
118
- --header "Name: value" Extra header (repeatable)
119
- --env-file <path> Path to .env file
120
- --proxy <url> HTTP(S) proxy URL
121
- --insecure Disable TLS certificate verification
122
- --ca-cert <path> Path to CA certificate bundle (PEM)
123
- --client-cert <path> Path to client certificate (PEM) for mTLS
124
- --client-key <path> Path to client private key (PEM) for mTLS
125
- --no-fail-on-error Exit 0 even if tests fail
126
- --config <path> Path to JSON config file
127
- --grpc-reflection Enable gRPC server reflection (default: true)
128
- --grpc-proto <path> Path to .proto file or directory (repeatable)
129
- --mcp-transport <mode> MCP transport: streamable-http or stdio (default: streamable-http)
130
- --mcp-command <cmd> MCP stdio command to spawn
131
- --mcp-args <args> MCP stdio command arguments (comma-separated)
132
- --mcp-cwd <dir> MCP stdio working directory
133
- -h, --help Show help
134
- -v, --version Show version
135
- ```
96
+ - [Official Website](https://www.powerduck.com/opensource/openapi-cli.html)
97
+ - [Documentation](https://www.powerduck.com/docs/openapi-cli/introduction)
98
+ - [GitHub](https://github.com/PowerDuckie/openapi-cli)
99
+ - [npm](https://www.npmjs.com/package/@powerduck/openapi-cli)
136
100
 
137
101
  ---
138
102
 
139
- ## Declarative Assertions (x-tests)
140
-
141
- Add an `x-tests` array to any operation. Each entry needs a `name` and an `assert` type:
142
-
143
- ```json
144
- {
145
- "paths": {
146
- "/users/{id}": {
147
- "get": {
148
- "operationId": "getUser",
149
- "x-tests": [
150
- { "name": "status is 200", "assert": "status", "value": 200 },
151
- { "name": "content-type is JSON", "assert": "header", "key": "content-type", "contains": "application/json" },
152
- { "name": "user id exists", "assert": "jsonPath", "path": "$.id", "exists": true },
153
- { "name": "user is active", "assert": "jsonPath", "path": "$.status", "equals": "active" },
154
- { "name": "response under 2s", "assert": "responseTime", "max": 2000 },
155
- { "name": "body contains email", "assert": "bodyContains", "contains": "@" }
156
- ],
157
- "responses": { "200": { "description": "ok" } }
158
- }
159
- }
160
- }
161
- }
162
- ```
163
-
164
- ### Assertion Types
103
+ ## Features
165
104
 
166
- | `assert` | Required fields | Purpose |
167
- |---|---|---|
168
- | `status` | `value` | HTTP status equals `value` |
169
- | `header` | `key`; optional `contains` | Header exists; optionally includes a substring |
170
- | `bodyContains` | `contains` | Response body includes the substring |
171
- | `bodyEquals` | `body` | Response body exactly equals `body` |
172
- | `jsonPath` | `path`; optional `equals` / `exists` | Resolve a JSONPath and compare or check existence |
173
- | `responseTime` | `max` | Duration must be `<= max` ms |
105
+ - **6 protocols** — HTTP/1.1, HTTP/2, HTTP/3, WebSocket, SSE, and gRPC
106
+ - **Batch testing** — Run every operation in your OpenAPI spec concurrently
107
+ - **Assertion engine** — Validate status codes, headers, response bodies, and schemas
108
+ - **3 report formats** — JSON for CI, CLI for terminal, HTML for dashboards
109
+ - **Authentication** — Bearer tokens, API keys, Basic auth, OAuth2, and custom headers
110
+ - **Filtering** — Run tests by tag, path, method, operationId, or regex
111
+ - **Concurrency control** — Configurable parallelism with rate limiting
112
+ - **gRPC reflection** — Auto-discover gRPC services via server reflection
113
+ - **MCP integration** — Streamable HTTP and stdio MCP transport support
114
+ - **GitHub Actions** — First-class CI integration with annotations and summaries
115
+ - **Config file support** — JSON config file with environment variable expansion
116
+ - **TLS/SSL options** — Custom CA certs, client certificates, and insecure mode
117
+ - **Proxy support** — HTTP/HTTPS proxy with authentication
118
+ - **Timeout & retries** — Configurable per-request timeout and retry policies
119
+ - **Dual ESM/CJS** — Works with `import` and `require`, with bundled TypeScript declarations
174
120
 
175
121
  ---
176
122
 
177
- ## Postman Scripts
123
+ ## CLI Reference
178
124
 
179
- Embed a full Postman test script via `x-postman-scripts`:
125
+ ### Commands
180
126
 
181
- ```json
182
- {
183
- "paths": {
184
- "/users": {
185
- "get": {
186
- "operationId": "listUsers",
187
- "x-postman-scripts": {
188
- "test": "pm.test('status is 200', () => pm.response.to.have.status(200)); pm.test('users is an array', () => pm.expect(pm.response.json().users).to.be.an('array'));"
189
- },
190
- "responses": { "200": { "description": "ok" } }
191
- }
192
- }
193
- }
194
- }
195
- ```
127
+ ```bash
128
+ openapi-cli [options]
196
129
 
197
- Declarative `x-tests` and `x-postman-scripts` may coexist on the same operation.
130
+ # Basic usage
131
+ openapi-cli --spec openapi.json --server https://api.example.com
198
132
 
199
- ---
133
+ # Filter by tag
134
+ openapi-cli --spec openapi.json --server https://api.example.com --tag users,orders
200
135
 
201
- ## Programmatic API
136
+ # Filter by method and path
137
+ openapi-cli --spec openapi.json --server https://api.example.com --method get --path "/users/*"
202
138
 
203
- ### `resolveConfig(args: CliArgs): CliConfig`
139
+ # Custom output
140
+ openapi-cli --spec openapi.json --server https://api.example.com --output ./reports --format json,html,cli
204
141
 
205
- Resolves CLI arguments into a normalized config. `CliArgs` uses string fields (`format`, `output`); `CliConfig` uses parsed fields (`formats` array, `outputDir` string).
142
+ # With auth
143
+ openapi-cli --spec openapi.json --server https://api.example.com --bearer $TOKEN --header "X-Env: staging"
206
144
 
207
- ```typescript
208
- const config = resolveConfig({
209
- spec: "./openapi.json",
210
- format: "json,html",
211
- output: "./reports",
212
- concurrency: 10,
213
- });
145
+ # Config file
146
+ openapi-cli --config ./openapi-cli.config.json
214
147
  ```
215
148
 
216
- ### `runTests(config: CliConfig): Promise<TestReport>`
217
-
218
- Runs all operations and returns a report.
219
-
220
- ### `generateJsonReport(report, outputDir): string`
221
-
222
- Writes `report.json` and returns the file path.
223
-
224
- ### `generateHtmlReport(report, outputDir): string`
225
-
226
- Writes a self-contained `report.html` and returns the file path.
227
-
228
- ---
229
-
230
- ## CliConfig Fields
231
-
232
- | Field | Type | Default | Description |
233
- |---|---|---|---|
234
- | `specPath` | `string` | **required** | Path or URL to OpenAPI 3.2 JSON spec |
235
- | `serverUrl` | `string` | *(from spec)* | Override server base URL |
236
- | `outputDir` | `string` | `"./openapi-cli-report"` | Directory for report files |
237
- | `formats` | `ReportFormat[]` | `["json","cli","html"]` | Report formats to generate |
238
- | `filter` | `FilterConfig` | `undefined` | Filter which operations to test |
239
- | `concurrency` | `number` | `5` | Max concurrent requests |
240
- | `timeout` | `number` | `30000` | Per-request timeout in ms |
241
- | `proxy` | `string` | `undefined` | HTTP(S) proxy URL |
242
- | `tls` | `TlsConfig` | `undefined` | TLS / certificate configuration |
243
- | `headers` | `Record<string, string>` | `undefined` | Extra headers sent with every request |
244
- | `auth` | `AuthConfig` | `undefined` | Authentication configuration |
245
- | `variables` | `Record<string, string>` | `undefined` | Postman `{{name}}` variables to inject |
246
- | `failOnError` | `boolean` | `true` | Exit with non-zero code if any test fails |
247
- | `envFile` | `string` | `undefined` | Path to a `.env` file |
248
- | `grpcReflection` | `boolean` | `true` | gRPC: use server reflection |
249
- | `grpcProtoPaths` | `string[]` | `undefined` | gRPC: paths to `.proto` files |
250
- | `mcpTransport` | `"streamable-http" \| "stdio"` | `"streamable-http"` | MCP transport |
251
- | `mcpCommand` | `string` | `undefined` | MCP stdio command |
252
- | `mcpArgs` | `string[]` | `undefined` | MCP stdio arguments |
253
- | `mcpCwd` | `string` | `undefined` | MCP stdio working directory |
149
+ ### Options
150
+
151
+ | Option | Type | Default | Description |
152
+ | ------------------ | ---------- | ---------------------- | ---------------------------------------- |
153
+ | `--spec` | `string` | - | Path or URL to OpenAPI spec (required) |
154
+ | `--server` | `string` | - | Server URL override |
155
+ | `--output` | `string` | `./openapi-cli-report` | Output directory |
156
+ | `--format` | `string` | `json,cli,html` | Output formats (comma-separated) |
157
+ | `--method` | `string` | - | Filter by HTTP method (comma-separated) |
158
+ | `--path` | `string` | - | Filter by path pattern (comma-separated) |
159
+ | `--tag` | `string` | - | Filter by tag (comma-separated) |
160
+ | `--operationId` | `string` | - | Filter by operationId (comma-separated) |
161
+ | `--concurrency` | `number` | `5` | Max concurrent requests |
162
+ | `--timeout` | `number` | `30000` | Request timeout in ms |
163
+ | `--bearer` | `string` | - | Bearer token for authentication |
164
+ | `--header` | `string[]` | - | Custom headers (Key: Value) |
165
+ | `--variable` | `string[]` | - | Server variables (key=value) |
166
+ | `--config` | `string` | - | Path to JSON config file |
167
+ | `--env` | `string` | - | Path to .env file |
168
+ | `--failOnError` | `boolean` | `true` | Exit with non-zero code on test failure |
169
+ | `--grpcReflection` | `boolean` | `true` | Enable gRPC server reflection |
170
+ | `--grpcProto` | `string[]` | - | gRPC proto file paths |
171
+ | `--mcpTransport` | `string` | `streamable-http` | MCP transport type |
172
+ | `--mcpCommand` | `string` | - | MCP server command (stdio) |
173
+ | `--mcpArgs` | `string` | - | MCP server arguments |
174
+ | `--mcpCwd` | `string` | - | MCP server working directory |
175
+ | `--proxy` | `string` | - | Proxy URL |
176
+ | `--ca` | `string` | - | CA certificate path |
177
+ | `--cert` | `string` | - | Client certificate path |
178
+ | `--key` | `string` | - | Client key path |
179
+ | `--insecure` | `boolean` | `false` | Disable SSL verification |
254
180
 
255
181
  ---
256
182
 
257
183
  ## Config File
258
184
 
259
- A JSON config file matching `Partial<CliConfig>`. Pass with `--config <path>`:
260
-
261
185
  ```json
262
186
  {
263
187
  "specPath": "./openapi.json",
264
- "serverUrl": "https://api.staging.example.com",
188
+ "serverUrl": "https://api.example.com",
265
189
  "outputDir": "./reports",
266
190
  "formats": ["json", "html"],
267
191
  "concurrency": 10,
268
- "timeout": 15000,
192
+ "timeout": 60000,
269
193
  "failOnError": true,
270
- "headers": {
271
- "X-API-Key": "${API_KEY}",
272
- "X-Environment": "staging"
194
+ "filter": {
195
+ "tags": ["users", "orders"],
196
+ "methods": ["get", "post"]
273
197
  },
274
198
  "auth": {
275
199
  "type": "bearer",
276
200
  "token": "${BEARER_TOKEN}"
277
201
  },
278
- "filter": {
279
- "methods": ["get", "post"],
280
- "tags": ["v2", "public"]
202
+ "headers": {
203
+ "X-Env": "staging"
204
+ },
205
+ "variables": {
206
+ "version": "v2"
281
207
  }
282
208
  }
283
209
  ```
284
210
 
285
- Environment variable expansion (`${VAR_NAME}`) is applied to `serverUrl`, `proxy`, `headers` values, `auth.token`, and `variables` values.
286
-
287
- ---
288
-
289
- ## Supported Protocols
290
-
291
- | Protocol | Identifier | How it is selected |
292
- |---|---|---|
293
- | HTTP | `http` | Default for every standard operation |
294
- | Server-Sent Events | `sse` | `text/event-stream` response content type, or `x-response-stream: true` |
295
- | WebSocket | `websocket` | `x-protocol: "websocket"` |
296
- | GraphQL | `graphql` | `x-protocol: "graphql"` |
297
- | gRPC | `grpc` | `x-protocol: "grpc"` |
298
- | MCP | `mcp` | `x-protocol: "mcp"` |
299
-
300
- Protocol can also be forced with the `x-protocol` extension on either the operation or the path item.
301
-
302
- ---
303
-
304
- ## Reports
305
-
306
- After a run, the tool writes (by default into `./openapi-cli-report`):
307
-
308
- - `report.json` — the complete `TestReport` object as pretty-printed JSON
309
- - `report.html` — a self-contained, dependency-free HTML report with a summary strip, progress bar, filter buttons, and expandable test rows
310
- - stdout — a colored CLI summary with a progress bar and per-test assertions
311
-
312
211
  ---
313
212
 
314
- ## Development
213
+ ## TypeScript Types
315
214
 
316
- ```bash
317
- # Install dependencies
318
- npm install
319
-
320
- # Type check
321
- npm run typecheck
322
-
323
- # Build (ESM + CJS + type declarations)
324
- npm run build
325
-
326
- # Run tests
327
- npm test
328
-
329
- # Watch mode
330
- npx vitest watch
215
+ ```typescript
216
+ import type {
217
+ CliConfig,
218
+ CliArgs,
219
+ TestReport,
220
+ TestResult,
221
+ AssertionResult,
222
+ } from "@powerduck/openapi-cli";
331
223
  ```
332
224
 
333
225
  ---
334
226
 
335
- ## Related Packages
336
-
337
- - [`@powerduck/openapi-request`](https://www.npmjs.com/package/@powerduck/openapi-request) — Execute OpenAPI operations with full parameter serialization
338
- - [`@powerduck/openapi-parser`](https://www.npmjs.com/package/@powerduck/openapi-parser) — OpenAPI 3.2 parser, validator, and upgrader
339
- - [`@powerduck/openapi-codegen`](https://www.npmjs.com/package/@powerduck/openapi-codegen) — Generate runnable request examples in 21 languages
340
- - [`@powerduck/x-to-openapi`](https://www.npmjs.com/package/@powerduck/x-to-openapi) — Convert curl commands and Postman Collections to OpenAPI 3.2
341
-
342
- ---
343
-
344
227
  ## License
345
228
 
346
- MIT
229
+ MIT © [POWERDUCK LIMITED](https://www.powerduck.com)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@powerduck/openapi-cli",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "CI-ready CLI for batch-testing OpenAPI documents across HTTP, SSE, WebSocket, GraphQL, gRPC and MCP",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",