pi-zephyr-testmanager

Zephyr Scale Cloud API integration for the pi coding agent — test cases, test cycles, and test executions for test-management workflows.

Status: published as a standalone, npm-installable pi package (TypeScript, loaded natively by pi — no build step).

The tool paths below reflect the publicly documented Zephyr Scale Cloud REST API v2 shape. Confirm /testexecutions update semantics and field names against your tenant's API docs before relying on write tools in production.

Installation

From npm:

pi install npm:pi-zephyr-testmanager

From git:

pi install git:github.com/your-github-username/pi-zephyr-testmanager

For a one-off session: pi -e npm:pi-zephyr-testmanager.

Quick Start

1. Generate a Zephyr Scale API access token (Jira profile → Zephyr Scale API Access Tokens).
2. Create ~/.pi/agent/pi-zephyr-testmanager.json with your token.
3. Run /zephyr-doctor to verify configuration and connectivity.

Example configuration

{
  "defaultSite": "acme",
  "safetyLevel": "confirm",
  "sites": [
    {
      "name": "acme",
      "apiToken": "your-zephyr-scale-api-token"
    }
  ]
}

baseUrl defaults to https://api.zephyrscale.smartbear.com/v2 and only needs to be set to override it (e.g. a different regional endpoint).

Mock mode

Set "mock": true to let zephyr_doctor validate config shape without making a live request.

Tools

Read

| Tool | Description | | --- | --- | | zephyr_doctor | Verify configuration and connection health | | zephyr_list_test_cases | List test cases for a project | | zephyr_get_test_case | Fetch a single test case, including its test script/steps | | zephyr_list_test_cycles | List test cycles for a project | | zephyr_get_test_cycle | Fetch a single test cycle | | zephyr_list_test_executions | List test executions, optionally scoped to a test cycle | | zephyr_get_test_execution | Fetch a single test execution |

Write (safety-gated)

| Tool | Description | | --- | --- | | zephyr_create_test_case | Create a test case | | zephyr_add_test_cases_to_cycle | Add one or more test cases to a test cycle (creates a test execution per test case) | | zephyr_update_test_execution_status | Record a test result (e.g. Pass/Fail) on a test execution |

Commands

| Command | Description | | --- | --- | | /zephyr-status | Show the current connection status (site, safety level) | | /zephyr-doctor | Check configuration, auth, and connection health |

Prompt templates

| Template | Description | | --- | --- | | /zephyr-cycle-status <projectKey> <testCycleIdOrKey> | Summarize a test cycle's execution progress | | /zephyr-record-result <testExecutionIdOrKey> <statusName> [comment] | Record a test result |

Configuration reference

| Key | Type | Default | Description | | --- | --- | --- | --- | | sites | array | — | List of { name, apiToken, baseUrl?, safetyLevel? } | | defaultSite | string | first site | Default site name used when a tool call omits site | | safetyLevel | string | "confirm" | Global default: "open", "confirm", or "readonly" | | mock | boolean | false | Skip live requests in zephyr_doctor for offline testing |

Network egress and corporate proxies

The client calls api.zephyrscale.smartbear.com directly over HTTPS and needs no extra config when outbound internet access is available. Set HTTPS_PROXY/HTTP_PROXY if an outbound proxy is required — the client builds an undici ProxyAgent from it automatically.

Safety levels

open / confirm (default) / readonly, resolved per-site override > global config > default.

| Level | Behavior | | --- | --- | | open | No confirmation before write tools run | | confirm (default) | Prompts via ctx.ui.confirm before create/add/update; blocked outright when no UI is available (e.g. print mode) | | readonly | All write tools blocked |

Architecture

• src/config.ts — load/validate ~/.pi/agent/pi-zephyr-testmanager.json, site/safety-level resolution
• src/auth.ts — Bearer auth header construction (API access token)
• src/proxy.ts — optional corporate-proxy dispatcher built from HTTPS_PROXY/HTTP_PROXY
• src/client.ts — fetch wrapper (JSON in/out, error normalization, 429 retry/backoff)
• src/safety.ts — mutation confirmation/blocking gate
• src/status.ts — footer status label + persistent connection card
• src/tools/{doctor,read,write}.ts — tool definitions
• src/index.ts — extension entry point, tool/command registration
• prompts/ — reusable prompt templates for common cycle/result workflows

Development

npm install
npm test        # node:test runner against src/*.test.ts — no live network calls
npm run check   # tsc --noEmit type-check

Run against a local checkout from anywhere with:

pi install /absolute/path/to/pi-zephyr-testmanager
# or, for a one-off session:
pi -e /absolute/path/to/pi-zephyr-testmanager

Requirements

• Node.js 22.19+ (pi runs .ts extension entries natively via type stripping)
• pi coding agent
• A Zephyr Scale Cloud API access token

License

MIT — see LICENSE.