Skill: ivangdavila/postman (version 1.0.0)

--- name: Postman slug: postman version: 1.0.0 homepage: https://clawic.com/skills/postman description: Build, test, and automate APIs with Postman collections, environments, and Newman CLI. metadata: {"clawdbot":{"emoji":"📮","requires":{"bins":["newman"]},"os":["linux","darwin","win32"],"install":[{"id":"npm","kind":"npm","package":"newman","bins":["newman"],"label":"Install Newman (npm)"}]}} changelog: Initial release with collections, environments, and Newman automation. --- ## Setup If `~/postman/` doesn't exist, read `setup.md` silently and start naturally. ## When to Use User needs to test APIs, create Postman collections, manage environments, or run automated API tests with Newman. ## Architecture Data lives in `~/postman/`. See `memory-template.md` for structure. ``` ~/postman/ ├── memory.md # Projects, preferences, common patterns ├── collections/ # Postman collection JSON files └── environments/ # Environment JSON files ``` ## Quick Reference | Topic | File | |-------|------| | Setup | `setup.md` | | Memory template | `memory-template.md` | | Collection format | `collections.md` | | Newman automation | `newman.md` | ## Core Rules ### 1. Collection Structure First Before creating requests, define the collection structure: - Folder hierarchy reflects API organization - Use descriptive names: `Users > Create User`, not `POST 1` - Group related endpoints logically ### 2. Environment Variables Always Never hardcode values that change between environments: ```json { "key": "base_url", "value": "https://api.example.com", "enabled": true } ``` Use `{{base_url}}` in requests. Environments: `dev`, `staging`, `prod`. ### 3. Pre-request Scripts for Auth Handle authentication in pre-request scripts, not manually: ```javascript // Get token and set for collection pm.sendRequest({ url: pm.environment.get("auth_url"), method: 'POST', body: { mode: 'raw', raw: JSON.stringify({...}) } }, (err, res) => { pm.environment.set("token", res.json().access_token); }); ``` ### 4. Test Assertions Required Every request needs at least basic assertions: ```javascript pm.test("Status 200", () => pm.response.to.have.status(200)); pm.test("Has data", () => pm.expect(pm.response.json()).to.have.property("data")); ``` ### 5. Newman for CI/CD Run collections headlessly with Newman: ```bash newman run collection.json -e environment.json --reporters cli,json ``` Exit code 0 = all tests passed. Integrate into CI pipelines. ## Collection Format ### Minimal Collection ```json { "info": { "name": "My API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Get Users", "request": { "method": "GET", "url": "{{base_url}}/users", "header": [ { "key": "Authorization", "value": "Bearer {{token}}" } ] } } ] } ``` ### With Tests ```json { "name": "Create User", "request": { "method": "POST", "url": "{{base_url}}/users", "body": { "mode": "raw", "raw": "{\"name\": \"{{$randomFullName}}\", \"email\": \"{{$randomEmail}}\"}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Created', () => pm.response.to.have.status(201));", "pm.test('Has ID', () => pm.expect(pm.response.json().id).to.exist);" ] } } ] } ``` ## Environment Format ```json { "name": "Development", "values": [ { "key": "base_url", "value": "http://localhost:3000", "enabled": true }, { "key": "token", "value": "", "enabled": true } ] } ``` ## Newman Commands | Task | Command | |------|---------| | Basic run | `newman run collection.json` | | With environment | `newman run collection.json -e dev.json` | | Specific folder | `newman run collection.json --folder "Users"` | | Iterations | `newman run collection.json -n 10` | | Data file | `newman run collection.json -d data.csv` | | HTML report | `newman run collection.json -r htmlextra` | | Bail on fail | `newman run collection.json --bail` | ## Common Traps - **Hardcoded URLs** → Tests break between environments. Always use `{{base_url}}`. - **No assertions** → Tests "pass" but don't validate anything. Add status + body checks. - **Secrets in collection** → Credentials leak. Use environment variables, gitignore env files. - **Sequential dependencies** → Tests fail randomly. Use `setNextRequest()` explicitly or make tests independent. - **Missing Content-Type** → POST/PUT fails silently. Always set `Content-Type: application/json`. ## Dynamic Variables Postman built-in variables for test data: | Variable | Example Output | |----------|----------------| | `{{$randomFullName}}` | "Jane Doe" | | `{{$randomEmail}}` | "[REDACTED_SECRET]" | | `{{$randomUUID}}` | "550e8400-e29b-..." | | `{{$timestamp}}` | 1234567890 | | `{{$randomInt}}` | 42 | ## OpenAPI to Postman Import OpenAPI/Swagger specs: 1. Export OpenAPI JSON/YAML 2. In Postman: Import > File > Select spec 3. Collection auto-generated with all endpoints Or via CLI: ```bash npx openapi-to-postmanv2 -s openapi.yaml -o collection.json ``` ## Security & Privacy **Data that stays local:** - Collections and environments in `~/postman/` - Newman runs locally **This skill does NOT:** - Send collections to external services - Store API credentials in memory.md ## Related Skills Install with `clawhub install <slug>` if user confirms: - `api` — REST API consumption patterns - `json` — JSON manipulation and validation - `ci-cd` — Pipeline automation ## Feedback - If useful: `clawhub star postman` - Stay updated: `clawhub sync`

path: collections.md
content: # Collections — Postman

## Full Collection Structure

```json
{
  "info": {
    "name": "API Name",
    "description": "API description",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{token}}" }]
  },
  "variable": [
    { "key": "base_url", "value": "https://api.example.com" }
  ],
  "item": []
}
```

## Request Templates

### GET with Query Params
```json
{
  "name": "List Items",
  "request": {
    "method": "GET",
    "url": {
      "raw": "{{base_url}}/items?page={{page}}&limit={{limit}}",
      "host": ["{{base_url}}"],
      "path": ["items"],
      "query": [
        { "key": "page", "value": "{{page}}" },
        { "key": "limit", "value": "{{limit}}" }
      ]
    }
  }
}
```

### POST with JSON Body
```json
{
  "name": "Create Item",
  "request": {
    "method": "POST",
    "url": "{{base_url}}/items",
    "header": [
      { "key": "Content-Type", "value": "application/json" }
    ],
    "body": {
      "mode": "raw",
      "raw": "{\n  \"name\": \"{{name}}\",\n  \"value\": {{value}}\n}",
      "options": { "raw": { "language": "json" } }
    }
  }
}
```

### PUT Update
```json
{
  "name": "Update Item",
  "request": {
    "method": "PUT",
    "url": "{{base_url}}/items/{{item_id}}",
    "header": [
      { "key": "Content-Type", "value": "application/json" }
    ],
    "body": {
      "mode": "raw",
      "raw": "{\n  \"name\": \"{{name}}\"\n}"
    }
  }
}
```

### DELETE
```json
{
  "name": "Delete Item",
  "request": {
    "method": "DELETE",
    "url": "{{base_url}}/items/{{item_id}}"
  }
}
```

### File Upload
```json
{
  "name": "Upload File",
  "request": {
    "method": "POST",
    "url": "{{base_url}}/upload",
    "body": {
      "mode": "formdata",
      "formdata": [
        { "key": "file", "type": "file", "src": "/path/to/file.pdf" },
        { "key": "description", "value": "My file", "type": "text" }
      ]
    }
  }
}
```

## Folder Organization

```json
{
  "item": [
    {
      "name": "Auth",
      "item": [
        { "name": "Login", "request": {...} },
        { "name": "Refresh Token", "request": {...} }
      ]
    },
    {
      "name": "Users",
      "item": [
        { "name": "List Users", "request": {...} },
        { "name": "Get User", "request": {...} },
        { "name": "Create User", "request": {...} }
      ]
    }
  ]
}
```

## Collection Variables vs Environment Variables

| Type | Use For | Example |
|------|---------|---------|
| Collection | Constants across all envs | API version, content types |
| Environment | Values that change | base_url, tokens, test data |

## Auth Inheritance

Set auth at collection level, requests inherit:

```json
{
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{token}}" }]
  }
}
```

Override per-request if needed (e.g., public endpoints).


path: memory-template.md
content: # Memory Template — Postman

Create `~/postman/memory.md` with this structure:

```markdown
# Postman Memory

## Status
status: ongoing
last: YYYY-MM-DD

## Projects

### Project Name
- Base URL: https://api.example.com
- Auth: Bearer token / API key / OAuth
- Environments: dev, staging, prod
- Collection: ~/postman/collections/project.json

## Patterns

### Authentication
<!-- Common auth approach they use -->

### Collection Structure
<!-- How they organize folders/requests -->

### Testing Conventions
<!-- Standard assertions they apply -->

## Notes
<!-- Preferences, quirks, things to remember -->

---
*Updated: YYYY-MM-DD*
```

## Folder Structure

```
~/postman/
├── memory.md
├── collections/
│   ├── project-a.json
│   └── project-b.json
└── environments/
    ├── dev.json
    ├── staging.json
    └── prod.json
```

## Status Values

| Value | Meaning |
|-------|---------|
| `ongoing` | Still learning their workflow |
| `complete` | Have good context |


path: newman.md
content: # Newman — Postman CLI

## Installation

```bash
npm install -g newman
```

## Basic Commands

```bash
# Run collection
newman run collection.json

# With environment
newman run collection.json -e environment.json

# With globals
newman run collection.json -g globals.json

# Multiple environments
newman run collection.json -e dev.json -e secrets.json
```

## Filtering

```bash
# Run specific folder
newman run collection.json --folder "Users"

# Run specific request (by name)
newman run collection.json --folder "Auth" --folder "Login"
```

## Iterations & Data

```bash
# Run 10 times
newman run collection.json -n 10

# With data file (CSV or JSON)
newman run collection.json -d users.csv

# Delay between requests (ms)
newman run collection.json --delay-request 500
```

### Data File Format (CSV)
```csv
email,password
[REDACTED_SECRET],pass1
[REDACTED_SECRET],pass2
```

### Data File Format (JSON)
```json
[
  { "email": "[REDACTED_SECRET]", "password": "pass1" },
  { "email": "[REDACTED_SECRET]", "password": "pass2" }
]
```

## Reporters

```bash
# CLI only (default)
newman run collection.json -r cli

# Multiple reporters
newman run collection.json -r cli,json,htmlextra

# JSON output to file
newman run collection.json -r json --reporter-json-export results.json

# HTML report (install: npm i -g newman-reporter-htmlextra)
newman run collection.json -r htmlextra --reporter-htmlextra-export report.html
```

## CI/CD Integration

### Exit Codes
- `0` — All tests passed
- `1` — Tests failed or errors occurred

### GitHub Actions
```yaml
- name: Run API Tests
  run: |
    npm install -g newman
    newman run collection.json -e ${{ env.ENV }}.json --bail
```

### GitLab CI
```yaml
api_tests:
  script:
    - npm install -g newman
    - newman run collection.json -e ci.json --reporters cli,junit --reporter-junit-export results.xml
  artifacts:
    reports:
      junit: results.xml
```

## Useful Flags

| Flag | Purpose |
|------|---------|
| `--bail` | Stop on first error |
| `--ignore-redirects` | Don't follow 3xx |
| `--insecure` | Allow self-signed certs |
| `--timeout 10000` | Request timeout (ms) |
| `--timeout-request 5000` | Per-request timeout |
| `--timeout-script 5000` | Script timeout |
| `-k` | Disable SSL verification |
| `--verbose` | Detailed output |

## Environment Variables in CI

```bash
# Override env values from shell
newman run collection.json \
  --env-var "base_url=$API_URL" \
  --env-var "[REDACTED_SECRET]"
```

## Common Patterns

### Smoke Test (fail fast)
```bash
newman run collection.json --folder "Health" --bail
```

### Full Test Suite with Report
```bash
newman run collection.json \
  -e staging.json \
  -r htmlextra,cli \
  --reporter-htmlextra-export ./reports/$(date +%Y%m%d).html
```

### Load Test Simulation
```bash
# Run 100 iterations with data
newman run collection.json -d users.json -n 100 --delay-request 100
```


path: setup.md
content: # Setup — Postman

Read this silently when `~/postman/` doesn't exist. Start naturally — never mention "setup" or file names.

## Your Attitude

You're helping someone work with APIs more efficiently. They might be testing an existing API, building a new one, or setting up automated tests.

## Priority Order

### 1. First: Integration

Within first 2-3 exchanges, understand their workflow:
- "Are you working with a specific API right now, or setting up testing infrastructure?"
- "Do you need to run tests in CI/CD, or is this for manual exploration?"

Save integration preferences to their MAIN memory.

### 2. Then: Understand Their Context

- What API(s) are they working with?
- Do they have existing collections to import?
- What's their environment setup? (local, staging, prod)
- Authentication method? (API key, OAuth, JWT)

### 3. Finally: Practical Setup

Help them create:
- Base environment file with their URL structure
- Collection skeleton matching their API organization
- Common auth pattern as pre-request script

## What You're Saving (internally)

In `~/postman/memory.md`:
- API projects they work with
- Preferred collection structure
- Authentication patterns
- Environment naming conventions

## Newman Installation

If they need automated testing, ensure Newman is installed:
```bash
npm install -g newman
```

For HTML reports:
```bash
npm install -g newman-reporter-htmlextra
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)