CI-Ready API Testing for OpenAPI

# Install globally
npm install -g @powerduck/openapi-cli

# Run tests from an OpenAPI spec (no subcommand, flat options)
openapi-cli --spec ./openapi.yaml

# With config file and HTML report
openapi-cli --config ./api-tests.json --format html --output ./reports

# Filter by tag and method
openapi-cli --spec ./openapi.yaml --tag users --method get

# Remote spec with auth
openapi-cli --spec https://api.example.com/openapi.json --bearer $TOKEN

// api-tests.json — complete config reference (JSON only, not YAML)
{
  // Required: path to OpenAPI 3.2 spec (JSON or YAML)
  "specPath": "./openapi.json",

  // Override server URL from the spec
  "serverUrl": "https://api.example.com/v1",

  // Report output (default: "./openapi-cli-report")
  "outputDir": "./reports",
  "formats": ["cli", "json", "html"],

  // Performance
  "concurrency": 5,
  "timeout": 30000,

  // Filter which operations to test
  "filter": {
    "methods": ["get", "post", "put", "delete"],
    "paths": ["^/users", "^/orders"],
    "tags": ["users", "orders"],
    "operationIds": ["getUser", "createOrder"]
  },

  // Authentication (bearer | basic | apikey | none)
  "auth": {
    "type": "bearer",
    "token": "${API_TOKEN}"
  },

  // Extra headers sent with every request
  "headers": {
    "X-Request-Id": "cli-test",
    "X-Environment": "staging"
  },

  // Postman variables ({{name}}) to inject
  "variables": {
    "baseUrl": "https://api.example.com",
    "userId": "123"
  },

  // Proxy & TLS
  "proxy": "http://proxy:8080",
  "tls": {
    "caCert": "./certs/ca.pem",
    "clientCert": "./certs/client.pem",
    "clientKey": "./certs/client-key.pem",
    "strictSSL": true
  },

  // Behavior
  "failOnError": true,
  "envFile": "./.env",

  // gRPC (optional)
  "grpcReflection": true,
  "grpcProtoPaths": ["./proto"],

  // MCP (optional)
  "mcpTransport": "streamable-http",
  "mcpCommand": "npx",
  "mcpArgs": ["@powerduck/openapi-mcp-server"],
  "mcpCwd": "./mcp-server"
}

import { runTests, resolveConfig, generateJsonReport, printCliReport } from "@powerduck/openapi-cli";

// Resolve config from CLI args (synchronous)
const config = resolveConfig({ spec: "./openapi.yaml" });

// Run all tests (async)
const report = await runTests(config);

// Print CLI report to stdout
printCliReport(report);

// Generate JSON report (synchronous, returns file path)
const reportPath = generateJsonReport(report, "./reports");

// Exit with non-zero code if tests failed
process.exit(report.summary.failed === 0 ? 0 : 1);

import { runDeclarativeAssertions, resolveJsonPath } from "@powerduck/openapi-cli";

// Assertion context (the response under test)
const ctx = {
  status: 200,
  headers: { "content-type": "application/json" },
  body: { data: { id: 1, name: "John" }, meta: { total: 100 } },
  durationMs: 150,
};

// Declarative assertions using the built-in assertion DSL
const assertions = [
  { name: "status is 200", assert: "status", value: 200 },
  { name: "content-type is json", assert: "header", key: "content-type", contains: "json" },
  { name: "name is John", assert: "jsonPath", path: "data.name", equals: "John" },
  { name: "total exists", assert: "jsonPath", path: "meta.total", exists: true },
  { name: "response under 1s", assert: "responseTime", max: 1000 },
];

// Run assertions (assertions first, context second)
const results = runDeclarativeAssertions(assertions, ctx);
console.log(results.every(r => r.passed) ? "All passed" : "Some failed");