@testsmith/api-spector 0.6.0 → 0.6.2

package/out/renderer/index.html

@@ -5,8 +5,10 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>API Spector</title>
-  <script type="module" crossorigin src="./assets/index-MMIHKSKx.js"></script>
-  <link rel="stylesheet" crossorigin href="./assets/index-CkHujZU3.css">
+  <script type="module" crossorigin src="./assets/index-D6-zmXen.js"></script>
+  <link rel="modulepreload" crossorigin href="./assets/codemirror-F6m3Hm1M.js">
+  <link rel="modulepreload" crossorigin href="./assets/ajv-2MAg6kGF.js">
+  <link rel="stylesheet" crossorigin href="./assets/index-B3mtLdU3.css">
 </head>
 
 <body>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@testsmith/api-spector",
   "productName": "API Spector",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Local-first API testing tool to inspect, test and mock APIs",
   "repository": {
     "type": "git",
@@ -26,7 +26,9 @@
     "bin/",
     "resources/splash.html",
     "build/icon.png",
-    "build/icon.ico"
+    "build/icon.ico",
+    "src/cli/agent-templates/",
+    "docs/ai/"
   ],
   "scripts": {
     "dev": "electron-vite dev",

package/src/cli/agent-templates/aider/conventions.md

@@ -0,0 +1,10 @@
+# API Spector Conventions
+
+This project uses API Spector for API testing. Reference docs are in `.aider/docs/`:
+
+- `api-spector-scripting-reference.md` — `sp.*` API (assertions, variables, TOTP, JSONPath)
+- `collection-file-format.md` — `.spector` and `.env.json` structure
+- `functional-testing-guide.md` — functional test design patterns
+- `security-testing-guide.md` — OWASP API Top 10 test patterns
+
+Use `sp.test()` for assertions, `sp.response.json()` for body parsing, `sp.environment.set()` for cross-request variables.

package/src/cli/agent-templates/claude/skills/api-spector-api-audit.md

@@ -0,0 +1,135 @@
+---
+name: Audit API for Inconsistencies
+description: Analyze an OpenAPI spec for design inconsistencies, naming violations, missing fields, and best-practice deviations
+---
+
+# Audit API for Inconsistencies
+
+Analyze an OpenAPI spec and produce a detailed audit report of design inconsistencies, naming violations, missing documentation, and deviations from REST best practices. This is a read-only analysis — no tests or collections are generated.
+
+## Execution steps — follow in order
+
+1. Ask the user for an OpenAPI spec URL or file path
+2. Fetch/read the spec
+3. Run every check listed below
+4. **Call the Write tool to create `api-audit-report.md` in the project directory.** Do NOT just print results in chat — write the full report to disk as a file.
+5. After writing, tell the user: "Audit report written to api-audit-report.md" and show a brief summary (total errors/warnings/info count) in chat.
+6. Rate each finding as: **error** (breaks clients), **warning** (inconsistent/confusing), or **info** (suggestion)
+
+## Checks to perform
+
+### 1. Naming consistency
+
+- **Path casing**: are paths consistently kebab-case (`/user-profiles`), snake_case (`/user_profiles`), or camelCase (`/userProfiles`)? Flag any that deviate from the majority.
+- **Path pluralization**: are collection endpoints plural (`/users`) and singleton endpoints singular (`/user/{id}`)? Flag inconsistent pluralization like `/user` for a list and `/products` for another list.
+- **Parameter naming**: are path/query params consistently camelCase, snake_case, or kebab-case? Flag mixed conventions (e.g. `userId` in one endpoint, `brand_id` in another).
+- **Schema property naming**: same casing check across all request/response schemas. Flag if some schemas use `firstName` and others use `first_name`.
+- **Operation IDs**: are they present? Are they consistently formatted (camelCase, snake_case)?
+
+### 2. HTTP method usage
+
+- **GET with request body**: GET endpoints should not have a request body. Flag any that do.
+- **POST for retrieval**: POST endpoints that only return data (no creation) — might be better as GET with query params.
+- **DELETE returning body**: flag DELETE endpoints that return 200 with a body (should typically be 204 No Content).
+- **PATCH vs PUT confusion**: flag PUT endpoints that accept partial updates (should be PATCH) or PATCH endpoints that require all fields (should be PUT).
+
+### 3. Response consistency
+
+- **Status codes**: do similar operations return the same codes? E.g. all successful creates return 201, all deletes return 204. Flag inconsistencies (one POST returns 200, another returns 201).
+- **Error schema**: do all error responses use the same shape? Flag if some return `{ "message": "..." }` and others return `{ "error": "..." }` or `{ "errors": [...] }`.
+- **Pagination**: do all list endpoints use the same pagination structure? Flag if some use `page/per_page`, others use `offset/limit`, and others have no pagination.
+- **Envelope consistency**: do some endpoints wrap data in `{ "data": [...] }` while others return bare arrays? Flag the inconsistency.
+
+### 4. Missing documentation
+
+- **Endpoints without descriptions**: list them.
+- **Parameters without descriptions**: list the count per endpoint.
+- **Schemas without property descriptions**: flag schemas where >50% of properties lack descriptions.
+- **Missing examples**: flag request/response schemas without examples (makes the spec harder to use).
+- **Missing operationId**: flag endpoints without operationId (breaks code generators).
+
+### 5. Schema issues
+
+- **Identical schemas with different names**: detect schemas that have the same properties/types but different names (copy-paste duplication).
+- **Overly permissive types**: flag `type: string` without `format`, `minLength`, `maxLength`, or `pattern` for fields that should be constrained (email, phone, URL, date).
+- **Missing required fields**: flag schemas that define properties like `id`, `email`, `name` but don't list them in `required`.
+- **Inconsistent ID types**: flag if some schemas use `type: integer` for IDs and others use `type: string`.
+- **Nullable vs optional confusion**: flag fields that are nullable but not marked as such, or optional fields that should be required.
+
+### 6. Security
+
+- **Endpoints without security**: flag endpoints that don't reference any security scheme (and aren't public-by-design like login/register).
+- **Inconsistent auth**: flag if some endpoints use Bearer tokens and others use API keys without clear reason.
+- **Sensitive data in query params**: flag endpoints that pass tokens, passwords, or keys as query parameters (should be headers or body).
+- **Missing security schemes**: flag if the spec references security schemes that aren't defined.
+
+### 7. Versioning & deprecation
+
+- **Mixed versioning**: flag if some paths use `/v1/...` and others use `/v2/...` or no version.
+- **Deprecated endpoints without replacement**: flag endpoints marked deprecated that don't document what to use instead.
+- **Deprecated endpoints without timeline**: flag deprecated endpoints that don't specify when they'll be removed.
+
+### 8. REST best practices
+
+- **Nested resources too deep**: flag paths with more than 3 levels of nesting (e.g. `/users/{id}/orders/{orderId}/items/{itemId}/details`).
+- **Verbs in paths**: flag paths that contain action verbs (e.g. `/getUser`, `/createOrder`, `/deleteProduct`) — the HTTP method should convey the action.
+- **Inconsistent trailing slashes**: flag if some paths end with `/` and others don't.
+- **Missing CORS headers in spec**: flag if no security headers or CORS configuration is documented.
+
+## Output format
+
+```markdown
+# API Audit Report: <API Name>
+
+**Spec**: <URL or file>
+**Version**: <spec version>
+**Endpoints analyzed**: <count>
+**Schemas analyzed**: <count>
+
+## Summary
+
+| Category | Errors | Warnings | Info |
+|---|---|---|---|
+| Naming consistency | 0 | 3 | 1 |
+| HTTP method usage | 1 | 0 | 0 |
+| Response consistency | 0 | 2 | 0 |
+| ... | ... | ... | ... |
+| **Total** | **1** | **5** | **1** |
+
+## Findings
+
+### Naming Consistency
+
+#### ⚠️ WARNING: Mixed parameter naming convention
+- `GET /users/{userId}` uses camelCase
+- `GET /brands/{brand_id}` uses snake_case
+- `GET /categories/{categoryId}` uses camelCase
+**Recommendation**: Standardize on one convention (snake_case is most common in REST APIs).
+
+#### ℹ️ INFO: Consider adding operationId to all endpoints
+- 12 out of 45 endpoints lack operationId
+**Recommendation**: Add operationId for better code generation support.
+
+### HTTP Method Usage
+
+#### 🔴 ERROR: GET endpoint has request body
+- `GET /reports/custom` defines a request body
+**Recommendation**: Use query parameters or POST for complex filters.
+
+...
+```
+
+## Important rules
+
+- This is **analysis only** — don't generate tests, collections, or code
+- Be specific: list the exact endpoints/schemas that have issues, don't just say "some endpoints"
+- Provide concrete recommendations for each finding
+- Don't flag things that are valid design choices (e.g. using UUIDs vs integers for IDs is a choice, not an inconsistency — unless both are used)
+- Group related findings (e.g. all naming issues together)
+- Count the total findings per severity in the summary table
+
+## Token efficiency
+
+- Don't reproduce the full spec in the output
+- Cite endpoints by method + path only
+- If 20+ endpoints have the same issue, show 3 examples and say "and N more"

package/src/cli/agent-templates/claude/skills/api-spector-functional-tests.md

@@ -0,0 +1,73 @@
+---
+name: Generate Functional Tests from OpenAPI
+description: Fetch an OpenAPI spec and generate an API Spector collection with functional test scripts
+---
+
+# Generate Functional Tests from OpenAPI
+
+## Execution steps — follow in order
+
+### 1. Get the spec
+
+Ask the user for an OpenAPI spec URL or file path. Fetch/read it.
+
+### 2. Create the workspace + collection + environment
+
+#### If workspace.json already exists
+
+Read it. Add the new collection/environment to existing arrays.
+
+#### If no workspace exists
+
+Create:
+```
+{project}/
+├── workspace.json
+├── collections/{name}.spector
+└── environments/{name}.env.json
+```
+
+Environment must include `baseUrl` from the spec + credential placeholders.
+
+### 3. Tell the user
+
+After creating everything, tell the user:
+- "Workspace created with collection and environment"
+- "Open the workspace in API Spector, fill in environment variables, and run"
+
+## URL and path parameters — CRITICAL
+
+NEVER use `:param` or `{param}`. Always use `{{variable}}`:
+- WRONG: `{{baseUrl}}/brands/:id`
+- RIGHT: `{{baseUrl}}/brands/{{brand_id}}`
+
+Every `{{var}}` in a URL must be set by a prior request via `sp.environment.set("var", ...)`.
+
+## Variable naming — CRITICAL
+
+Use simple snake_case. The name in `sp.environment.set("x", ...)` MUST exactly match every `{{x}}` reference.
+
+Before outputting, build a dependency chain and verify every `{{var}}` has a matching setter that runs first.
+
+## Collection structure
+
+- One folder per API tag
+- `beforeAll` login hook that extracts `{{access_token}}`
+- ONE request per test scenario
+- `postRequestScript` with `sp.test()` assertions
+- Path params as `paramType: "path"` in params array AND `{{var}}` in URL
+- Use `{{baseUrl}}` prefix
+- Order: list/create before get/update/delete (so IDs are extracted first)
+
+## References
+
+- `.claude/docs/api-spector-scripting-reference.md` — `sp.*` API
+- `.claude/docs/functional-testing-guide.md` — test patterns
+- `.claude/docs/collection-file-format.md` — JSON format
+
+## Token efficiency
+
+- Extract only paths, methods, required fields from spec
+- Ask which tags to cover, generate one at a time
+- Skip boilerplate headers (Accept/Content-Type are defaults)
+- Use compact JSON

package/src/cli/agent-templates/claude/skills/api-spector-generate-mocks.md

@@ -0,0 +1,182 @@
+---
+name: Generate Mock Server from OpenAPI
+description: Create an API Spector mock server with dynamic responses from an OpenAPI spec
+---
+
+# Generate Mock Server from OpenAPI
+
+## What to do
+
+1. Ask the user for an OpenAPI spec URL or file path
+2. Ask which endpoints/tags to mock (or all)
+3. Ask what port to use (default: 3900)
+4. Generate a `.mock.json` file with routes for each endpoint
+
+## Mock server file format
+
+```json
+{
+  "version": "1.0",
+  "id": "uuid",
+  "name": "My API Mock",
+  "port": 3900,
+  "routes": [
+    {
+      "id": "uuid",
+      "method": "GET",
+      "path": "/users/:id",
+      "statusCode": 200,
+      "headers": { "Content-Type": "application/json" },
+      "body": "{ ... }",
+      "description": "Get user by ID",
+      "script": "// optional JS to make response dynamic"
+    }
+  ]
+}
+```
+
+### Route fields
+- `method`: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, or ANY
+- `path`: Express-style with `:param` for path params (e.g. `/users/:id`)
+- `statusCode`: default HTTP status
+- `headers`: response headers (Content-Type defaults to application/json)
+- `body`: static JSON string response body
+- `script`: JavaScript that runs before sending. Has access to `request`, `response`, `faker`, `dayjs`
+- `delay`: optional ms delay before responding
+
+### Path params
+
+Use Express-style `:param` syntax, NOT OpenAPI `{param}`:
+- OpenAPI: `/users/{userId}` → Mock: `/users/:userId`
+
+### Script context
+
+```javascript
+// Available in route scripts:
+request.method     // "GET"
+request.path       // "/users/42"
+request.params     // { id: "42" }
+request.query      // { page: "1" }
+request.body       // parsed JSON body (or null)
+request.headers    // { authorization: "Bearer ...", ... }
+
+response.statusCode  // mutable — change to e.g. 404
+response.body        // mutable — replace the response body
+response.headers     // mutable — add/change headers
+
+faker                // @faker-js/faker — generate dynamic data
+dayjs                // dayjs — date/time helpers
+```
+
+## Making responses dynamic
+
+Use `script` on routes to generate realistic data with faker:
+
+### List endpoint with faker data
+```json
+{
+  "method": "GET",
+  "path": "/users",
+  "statusCode": 200,
+  "body": "[]",
+  "script": "const users = Array.from({length: 10}, (_, i) => ({ id: i + 1, name: faker.person.fullName(), email: faker.internet.email(), role: faker.helpers.arrayElement(['admin', 'user']), created_at: faker.date.recent().toISOString() })); response.body = JSON.stringify(users);"
+}
+```
+
+### Single resource using path param
+```json
+{
+  "method": "GET",
+  "path": "/users/:id",
+  "statusCode": 200,
+  "body": "{}",
+  "script": "response.body = JSON.stringify({ id: request.params.id, name: faker.person.fullName(), email: faker.internet.email(), created_at: faker.date.recent().toISOString() });"
+}
+```
+
+### POST that echoes back with generated ID
+```json
+{
+  "method": "POST",
+  "path": "/users",
+  "statusCode": 201,
+  "body": "{}",
+  "script": "const body = request.body || {}; response.body = JSON.stringify({ id: faker.string.uuid(), ...body, created_at: dayjs().toISOString() });"
+}
+```
+
+### Conditional responses (not found, validation)
+```json
+{
+  "method": "GET",
+  "path": "/users/:id",
+  "statusCode": 200,
+  "body": "{}",
+  "script": "if (request.params.id === '0' || request.params.id === 'notfound') { response.statusCode = 404; response.body = JSON.stringify({ message: 'User not found' }); } else { response.body = JSON.stringify({ id: request.params.id, name: faker.person.fullName() }); }"
+}
+```
+
+### Auth validation mock
+```json
+{
+  "method": "GET",
+  "path": "/users/me",
+  "statusCode": 200,
+  "body": "{}",
+  "script": "if (!request.headers.authorization) { response.statusCode = 401; response.body = JSON.stringify({ message: 'Unauthorized' }); } else { response.body = JSON.stringify({ id: 1, name: faker.person.fullName(), email: faker.internet.email() }); }"
+}
+```
+
+## What to generate per endpoint type
+
+| OpenAPI pattern | Mock behavior |
+|---|---|
+| `GET /resources` (list) | faker array of 5-10 items with realistic field values |
+| `GET /resources/:id` | faker single item using `request.params.id` |
+| `POST /resources` | 201 + echo body with generated `id` and `created_at` |
+| `PUT /resources/:id` | 200 + echo body merged with `request.params.id` |
+| `PATCH /resources/:id` | 200 + echo body merged with `request.params.id` |
+| `DELETE /resources/:id` | 204 + empty body |
+| Auth endpoint (`POST /login`) | Return `{ access_token: faker.string.uuid() }` |
+
+## When to use static vs dynamic
+
+- **IDs, timestamps, emails, names**: always dynamic (faker)
+- **Enum fields** (status, role, type): use `faker.helpers.arrayElement([...])`
+- **Booleans**: use `faker.datatype.boolean()`
+- **Prices/amounts**: use `faker.number.float({ min: 1, max: 999, fractionDigits: 2 })`
+- **Fixed structure fields** (pagination meta, error shapes): static in `body`
+- **Path-param-dependent data**: use `request.params.x` in scripts
+
+## Token efficiency
+
+- Extract only paths, methods, and response schemas from the spec — skip descriptions
+- Ask which tags to mock before generating all
+- Generate compact JSON
+- One script per route, no comments in scripts (they're in `description` field)
+
+## File output — create or update workspace
+
+### If no workspace.json exists, create the full workspace:
+
+```
+<project>/
+├── workspace.json
+└── mocks/
+    └── <api-name>.mock.json
+```
+
+`workspace.json`:
+```json
+{
+  "version": "1.0",
+  "collections": [],
+  "environments": [],
+  "mocks": ["mocks/<api-name>.mock.json"],
+  "activeEnvironmentId": null
+}
+```
+
+### If workspace.json already exists:
+
+Add the mock file path to the existing `mocks` array (create the array if it doesn't exist). Don't overwrite collections or environments.

package/src/cli/agent-templates/claude/skills/api-spector-security-tests.md

@@ -0,0 +1,73 @@
+---
+name: Generate Security Tests from OpenAPI (OWASP API Top 10)
+description: Generate OWASP API Top 10 security test cases with attack payloads for API Spector
+---
+
+# Generate Security Tests from OpenAPI (OWASP API Top 10)
+
+## Execution steps — follow in order
+
+### 1. Get the spec
+
+Ask the user for an OpenAPI spec URL or file path. Fetch/read it.
+
+### 2. Analyze auth
+
+Check the spec for `securityDefinitions`, `security`, `securitySchemes`, or login endpoints.
+
+- **No auth found** → skip BOLA, Broken Auth, Function-Level Auth. Only generate: Injection, Security Config, Resource Consumption, SSRF. Do NOT ask for credentials.
+- **Auth found** → ask for credential variable names (`{{user_a_token}}`, `{{user_b_token}}`, `{{admin_token}}`, `{{user_b_id}}`).
+
+### 3. Create the workspace + collection + environment
+
+#### If workspace.json already exists
+
+Read it. Add the new security collection/environment to existing arrays.
+
+#### If no workspace exists
+
+Create:
+```
+{project}/
+├── workspace.json
+├── collections/{name}-security.spector
+└── environments/{name}.env.json
+```
+
+Environment must include `baseUrl` from the spec + credential placeholders (if auth exists).
+
+### 4. Tell the user
+
+After creating everything, tell the user:
+- "Workspace created with security collection and environment"
+- "Open the workspace in API Spector, fill in environment variables, and run"
+
+## Applicability rules
+
+| Condition | BOLA | Auth | Mass Assign | Func Auth | Injection | SSRF | Config | Resources |
+|---|---|---|---|---|---|---|---|---|
+| Has auth + user IDs in paths | YES | YES | YES | YES | YES | maybe | YES | YES |
+| Has auth, no user IDs | no | YES | YES | maybe | YES | maybe | YES | YES |
+| No auth at all | no | no | maybe | no | YES | maybe | YES | YES |
+
+## URL syntax — CRITICAL
+
+NEVER use `:param` or `{param}`. Always use `{{variable}}`:
+- WRONG: `{{baseUrl}}/users/:id`
+- RIGHT: `{{baseUrl}}/users/{{user_b_id}}`
+
+## Variable naming — CRITICAL
+
+Use consistent snake_case. `sp.environment.set("x", ...)` must match `{{x}}` everywhere.
+
+## References
+
+- `.claude/docs/api-spector-scripting-reference.md` — `sp.*` API
+- `.claude/docs/security-testing-guide.md` — OWASP patterns
+- `.claude/docs/collection-file-format.md` — JSON format
+
+## Token efficiency
+
+- Ask which OWASP categories to focus on before generating all
+- Skip categories that don't apply
+- Generate in batches if 20+ endpoints

package/src/cli/agent-templates/copilot/copilot-instructions.md

@@ -0,0 +1,38 @@
+# GitHub Copilot Instructions — API Spector
+
+This project uses **API Spector**, a local-first API testing tool. When working with test scripts, collections, or test generation, refer to the documentation in `.github/docs/`.
+
+## Key references
+
+- **Scripting API**: See `.github/docs/api-spector-scripting-reference.md` for the full `sp.*` API (assertions, response access, variables, TOTP, JSONPath)
+- **Collection format**: See `.github/docs/collection-file-format.md` for `.spector` file structure
+- **Functional testing**: See `.github/docs/functional-testing-guide.md` for test design patterns
+- **Security testing**: See `.github/docs/security-testing-guide.md` for OWASP API Top 10 patterns
+
+## Quick reference
+
+Scripts use the `sp` global:
+
+```javascript
+// Test assertion
+sp.test('name', function() {
+  const json = sp.response.json();
+  sp.expect(json.field).to.equal("value");
+});
+
+// Variable extraction
+sp.environment.set("token", String(sp.response.json().access_token));
+
+// Status check
+sp.expect(sp.response.code).to.equal(200);
+```
+
+Variables use `{{name}}` interpolation in URLs, headers, body, and scripts.
+
+## When asked to generate tests
+
+1. Read the relevant `.github/docs/` guide
+2. Use `sp.test()` blocks with descriptive names
+3. Parse JSON once: `const json = sp.response.json();`
+4. Cover: happy path, missing fields, wrong types, auth, edge cases
+5. Use `sp.environment.set()` for cross-request data flow

package/src/cli/agent-templates/cursor/rules/api-spector.mdc

@@ -0,0 +1,21 @@
+---
+description: API Spector API testing tool — scripting API, collection format, and test generation
+globs: ["**/*.spector", "**/*.env.json", "**/workspace.json"]
+---
+
+# API Spector
+
+This project uses API Spector for API testing. When editing collection files (`.spector`), environment files (`.env.json`), or generating test scripts, follow these references:
+
+- `.cursor/docs/api-spector-scripting-reference.md` — Full `sp.*` scripting API
+- `.cursor/docs/collection-file-format.md` — `.spector` and `.env.json` file structure
+- `.cursor/docs/functional-testing-guide.md` — Functional test design patterns
+- `.cursor/docs/security-testing-guide.md` — OWASP API Top 10 security tests
+
+## Script conventions
+
+- Wrap assertions in `sp.test('descriptive name', function() { ... })`
+- Parse JSON once per script: `const json = sp.response.json();`
+- Use `sp.environment.set("key", value)` to pass data between requests
+- Use `{{variable}}` interpolation in URLs, headers, body, and scripts
+- Hooks: `beforeAll` runs once per folder, `before` runs per request

package/src/cli/agent-templates/windsurf/windsurfrules

@@ -0,0 +1,19 @@
+# API Spector — Windsurf Rules
+
+This project uses API Spector for API testing.
+
+## References
+
+When working with test scripts or collection files, read:
+- `.windsurf/docs/api-spector-scripting-reference.md` — Full `sp.*` scripting API
+- `.windsurf/docs/collection-file-format.md` — Collection and environment file format
+- `.windsurf/docs/functional-testing-guide.md` — Functional test patterns
+- `.windsurf/docs/security-testing-guide.md` — OWASP API Top 10 test patterns
+
+## Script conventions
+
+- Use `sp.test('name', function() { ... })` for assertions
+- Use `sp.expect(value)` with `.to.equal()`, `.to.include()`, `.to.be.a()`, etc.
+- Parse body: `const json = sp.response.json();`
+- Set variables: `sp.environment.set("key", "value")`
+- Use `{{variable}}` in URLs, headers, body, and scripts