version: 1
metadata:
  key: "api-test-postman"
  last_verified: "2026-08-07"
interface:
  display_name: "Postman API Testing"
  short_description: "Design Postman collections, environments, scripts, and Newman-ready API regression plans."
  default_prompt: "Use api-test-postman to complete the task with local prompts, references, and examples in this skill folder."
policy:
  allow_implicit_invocation: true

schema_version: v1alpha1

environment:
  type: none

skills:
  - source: local_path
    path: .

engine:
  name: claude_code
  # model is optional; omit to use engine default
  # model:
  #   provider: anthropic
  #   name: claude-sonnet-4-6

cases:
  files:
    - evals/cases/basic-success.yaml
    - evals/cases/edge-incomplete-input.yaml
    - evals/cases/edge-scope-boundary.yaml
  defaults:
    timeout_seconds: 180
    max_turns: 8
    expect:
      exit_code: 0
      must_not_contain:
        - "TODO"
        - "I cannot"
        - "我无法"

benchmark:
  enabled: true

report:
  formats: [json]

# Sample Context

Use `@skill api-test-postman` to design coverage for a release-critical login and checkout flow.

Project context:

- Tool: Postman API Testing
- Environment: staging
- Priority: protect the release smoke path and the highest-risk regression cases
- Constraints: keep the first version maintainable and CI-friendly

Expected output:

- Postman collection plan
- environment and variable design
- assertion and script checklist
- Newman execution notes

# Output Template

## Summary
- Scope:
- Key Risks:

## Tool-Specific Plan
- Structure:
- Data:
- Assertions:
- Execution:

## Open Questions
- Question 1:

# Postman API Testing Prompt

Design Postman API testing assets or a Postman-ready plan that the team can implement directly.

## Role

- Act as a senior QA automation expert who structures outputs for practical Postman usage.

## Input

- OpenAPI, curl, Postman collection, endpoint notes, or auth docs
- environment, release scope, and regression priorities
- current Newman or CI constraints

## What to do

1. Understand the target scope and highest-risk flows first.
2. Organize the result around real Postman API testing workflows, not generic testing theory.
3. Keep assumptions visible when project details are incomplete.

## Execution Rules

- Cover tool-specific structure, execution, data, assertions, reporting, and CI concerns when relevant.
- Prefer maintainable test organization over large one-off scripts.
- If information is incomplete, give a usable first version and mark assumptions.

## Minimum Coverage Checklist

Unless the user explicitly narrows the scope, make sure the result addresses these items:
- collection structure
- environment and variable strategy
- pre-request and test scripts
- Newman and CI execution
- API regression risk coverage
- test data or environment needs
- reporting needs
- missing information and assumptions

## Output

Return the result in this order:

### 1. Task Understanding
### 2. Postman API Testing Scope
### 3. Test Structure and Coverage
### 4. Data, Environment, and Assertions
### 5. Execution and CI Notes
### 6. Open Questions

## Quality Bar

- Keep the result Postman API testing-oriented.
- Do not output unrelated framework advice.
- Avoid long code unless the user asks for runnable files.

# Postman API Testing Framework Notes

## Primary Focus

- collection structure
- environment and variable strategy
- pre-request and test scripts
- Newman and CI execution
- API regression risk coverage

## Recommended Structure

- Start from business-critical flows or endpoints.
- Group tests by product capability and execution risk.
- Keep setup, data, assertions, and reporting visible in the plan.
- Prefer maintainable naming and reusable helpers over large scripts.

## Decision Rules

- Use this skill when Postman is the chosen or likely tool.
- Use the generic parent testing skill when the tool is still undecided.
- Call out constraints that make another tool a better fit.

# Postman API Testing Setup and CI Notes

## Local Setup

- Confirm the tool version and runtime before proposing commands.
- Keep secrets, tokens, and environment-specific values outside committed test files.
- Store generated reports under a reports or build-artifacts folder ignored by version control.

## Suggested Run Command

```bash
newman run "${COLLECTION:-collection.json}" -e "${ENVIRONMENT:-environment.json}" --reporters cli,json --reporter-json-export "$REPORT_JSON"
```

## CI Guidance

- Run smoke coverage on pull requests.
- Run broader regression on release branches or scheduled jobs.
- Preserve reports, logs, screenshots, traces, or result files as CI artifacts when the tool produces them.
- Fail the pipeline on clear assertion failures, not on missing optional artifacts.

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
REPORT_DIR="$SCRIPT_DIR/../reports"
mkdir -p "$REPORT_DIR"
TS="$(date +%Y%m%d-%H%M%S)"
REPORT_JSON="$REPORT_DIR/api-test-postman-$TS.json"

echo "Running api-test-postman lightweight entry point"
echo "Report path: $REPORT_JSON"

newman run "${COLLECTION:-collection.json}" -e "${ENVIRONMENT:-environment.json}" --reporters cli,json --reporter-json-export "$REPORT_JSON"