# 使用 winget 安裝（Windows 套件管理器）
winget install Postman.Postman

# 使用 Chocolatey 安裝
choco install postman

# 使用 Homebrew 安裝
brew install --cask postman

# Ubuntu / Debian（Snap）
sudo snap install postman

# Flatpak
flatpak install flathub com.getpostman.Postman

# 手動安裝（tar.gz）
wget https://dl.pstmn.io/download/latest/linux_64 -O postman-linux.tar.gz
tar -xzf postman-linux.tar.gz -C /opt
ln -s /opt/Postman/Postman /usr/local/bin/postman

# Windows：將企業 CA 加入信任根憑證
certutil -addstore -user Root "C:\certs\company-ca.crt"

# macOS：將 CA 加入鑰匙圈
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain company-ca.crt

📁 Team Workspace: "Order Service API"
├── 📂 Collections
│   ├── 📋 Order API v2
│   ├── 📋 Order API v1 (deprecated)
│   └── 📋 Integration Tests
├── 🌐 Environments
│   ├── dev
│   ├── sit
│   ├── uat
│   └── prod
├── 🎭 Mock Servers
│   └── Order Mock v2
├── 📡 Monitors
│   └── Order Health Check
└── 📖 APIs
    └── Order API (OpenAPI 3.1)

{{baseUrl}}/api/v1/orders/{{orderId}}

{
  "token": "{{accessToken}}",
  "userId": "{{userId}}"
}

// 在腳本中使用 console 進行除錯
console.log("Request URL:", pm.request.url.toString());
console.log("Environment:", pm.environment.get("env_name"));
console.info("Token expires at:", pm.environment.get("tokenExpiry"));
console.warn("Token will expire soon!");
console.error("Authentication failed!");

GET {{baseUrl}}/api/v1/orders?status=active&page=1&size=20

POST {{baseUrl}}/api/v1/orders
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
  "customerId": "{{customerId}}",
  "items": [
    {
      "productId": "PROD-001",
      "quantity": 2,
      "unitPrice": 150.00
    }
  ],
  "shippingAddress": {
    "city": "台北市",
    "district": "信義區",
    "address": "市府路1號"
  }
}

GET {{baseUrl}}/api/v1/orders/:orderId/items/:itemId

// Post-response Script 中自訂視覺化
const template = `
<table>
  <tr><th>ID</th><th>Name</th><th>Status</th></tr>
  {{#each response}}
  <tr><td>{{id}}</td><td>{{name}}</td><td>{{status}}</td></tr>
  {{/each}}
</table>
`;

pm.visualizer.set(template, {
  response: pm.response.json().data
});

query GetOrders($status: OrderStatus, $limit: Int) {
  orders(status: $status, limit: $limit) {
    id
    customerName
    totalAmount
    status
    createdAt
    items {
      productName
      quantity
    }
  }
}

{
  "status": "ACTIVE",
  "limit": 10
}

Local > Data > Environment > Collection > Global

// Collection Variable（設一次，所有請求共用）
// 在 Collection Variables Tab 設定：
// apiVersion = "v2"
// baseUrl 不設，留給 Environment

// Environment Variable（依環境切換）
// dev: baseUrl = "http://localhost:8080"
// sit: baseUrl = "https://sit-api.company.com"
// prod: baseUrl = "https://api.company.com"

// 請求 URL 引用：
// {{baseUrl}}/api/{{apiVersion}}/orders

// 在腳本中取得動態變數值
const uuid = pm.variables.replaceIn("{{$guid}}");
const timestamp = pm.variables.replaceIn("{{$timestamp}}");

// 設定為環境變數供後續請求使用
pm.environment.set("requestId", uuid);
pm.environment.set("requestTime", timestamp);

📁 Environments
├── 🟢 dev          → localhost / 開發機
├── 🟡 sit          → 系統整合測試環境
├── 🟠 uat          → 使用者驗收測試環境
├── 🔴 prod         → 正式環境（唯讀建議）
└── 🔵 sandbox      → 第三方 API 沙箱

// 依環境動態調整行為
if (pm.environment.name === "prod") {
    console.warn("⚠️ 正在對生產環境發送請求！");
}

// Azure Key Vault 整合設定
// Settings → Vault → Add Vault Integration
// Provider: Azure Key Vault
// Vault URL: https://my-vault.vault.azure.net/
// Authentication: Service Principal (Client ID + Secret)

email,password,expectedStatus,expectedMessage
admin@company.com,Admin123!,200,Login successful
user@company.com,User456!,200,Login successful
invalid@company.com,wrong,401,Invalid credentials
,Admin123!,400,Email is required
admin@company.com,,400,Password is required

[
  {
    "email": "admin@company.com",
    "password": "Admin123!",
    "expectedStatus": 200,
    "expectedMessage": "Login successful"
  },
  {
    "email": "invalid@company.com",
    "password": "wrong",
    "expectedStatus": 401,
    "expectedMessage": "Invalid credentials"
  }
]

// Request Body 中引用（與一般變數相同）
// {{email}} 和 {{password}} 會自動替換為資料檔中的值

// Post-response Script 中驗證
pm.test("Status code matches expected", function () {
    pm.response.to.have.status(parseInt(pm.iterationData.get("expectedStatus")));
});

pm.test("Response message matches expected", function () {
    const response = pm.response.json();
    pm.expect(response.message).to.eql(pm.iterationData.get("expectedMessage"));
});

const crypto = require('crypto-js');
const timestamp = Math.floor(Date.now() / 1000).toString();
const secretKey = pm.environment.get("apiSecret");
const requestBody = pm.request.body.raw;

// 計算 HMAC-SHA256 簽章
const signature = crypto.HmacSHA256(timestamp + requestBody, secretKey).toString();

// 設定到 Header
pm.request.headers.add({
    key: "X-Timestamp",
    value: timestamp
});
pm.request.headers.add({
    key: "X-Signature",
    value: signature
});

const tokenExpiry = pm.environment.get("tokenExpiry");
const currentTime = Math.floor(Date.now() / 1000);

if (!tokenExpiry || currentTime >= parseInt(tokenExpiry) - 60) {
    // Token 即將過期或不存在，發送刷新請求
    pm.sendRequest({
        url: pm.environment.get("authUrl") + "/token",
        method: "POST",
        header: {
            "Content-Type": "application/x-www-form-urlencoded"
        },
        body: {
            mode: "urlencoded",
            urlencoded: [
                { key: "grant_type", value: "client_credentials" },
                { key: "client_id", value: pm.environment.get("clientId") },
                { key: "client_secret", value: pm.environment.get("clientSecret") }
            ]
        }
    }, function (err, res) {
        if (err) {
            console.error("Token refresh failed:", err);
            return;
        }
        const token = res.json();
        pm.environment.set("accessToken", token.access_token);
        pm.environment.set("tokenExpiry", String(currentTime + token.expires_in));
        console.log("Token refreshed successfully");
    });
}

// 每個 pm.test() 定義一個測試案例
pm.test("Test case name", function () {
    // 使用 pm.expect() 或 pm.response 進行斷言
    pm.expect(pm.response.code).to.eql(200);
});

// 1. 驗證 Status Code
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

// 2. 驗證回應時間
pm.test("Response time is less than 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// 3. 驗證回應 Header
pm.test("Content-Type is application/json", function () {
    pm.response.to.have.header("Content-Type", "application/json; charset=utf-8");
});

// 4. 驗證 JSON Body 結構
pm.test("Response has correct structure", function () {
    const response = pm.response.json();
    pm.expect(response).to.have.property("data");
    pm.expect(response).to.have.property("meta");
    pm.expect(response.data).to.be.an("array");
    pm.expect(response.meta).to.have.property("total");
    pm.expect(response.meta).to.have.property("page");
});

// 5. 驗證資料內容
pm.test("First order has required fields", function () {
    const order = pm.response.json().data[0];
    pm.expect(order).to.have.all.keys("id", "customerId", "status", "totalAmount", "createdAt");
    pm.expect(order.status).to.be.oneOf(["ACTIVE", "COMPLETED", "CANCELLED"]);
    pm.expect(order.totalAmount).to.be.a("number").and.to.be.above(0);
});

// 6. 擷取回應資料供下一個請求使用
const firstOrderId = pm.response.json().data[0].id;
pm.environment.set("orderId", firstOrderId);
console.log("Captured orderId:", firstOrderId);

// 相等
pm.expect(value).to.eql(expected);         // 深度相等（推薦）
pm.expect(value).to.equal(expected);       // 嚴格相等（===）

// 類型
pm.expect(value).to.be.a("string");
pm.expect(value).to.be.an("array");
pm.expect(value).to.be.a("number");
pm.expect(value).to.be.an("object");
pm.expect(value).to.be.a("boolean");
pm.expect(value).to.be.null;
pm.expect(value).to.be.undefined;

// 比較
pm.expect(value).to.be.above(10);          // >
pm.expect(value).to.be.below(100);         // <
pm.expect(value).to.be.at.least(1);        // >=
pm.expect(value).to.be.at.most(50);        // <=
pm.expect(value).to.be.within(1, 100);     // 範圍

// 包含
pm.expect(string).to.include("substr");
pm.expect(array).to.include("item");
pm.expect(object).to.have.property("key");
pm.expect(object).to.have.all.keys("a", "b", "c");
pm.expect(object).to.have.any.keys("a", "b");

// 長度
pm.expect(array).to.have.lengthOf(5);
pm.expect(array).to.have.length.above(0);
pm.expect(string).to.have.lengthOf.at.least(1);

// 正則
pm.expect(string).to.match(/^[A-Z]{2}-\d+$/);

// 否定
pm.expect(value).to.not.eql(unexpected);
pm.expect(array).to.not.be.empty;

// 布林
pm.expect(value).to.be.true;
pm.expect(value).to.be.false;
pm.expect(value).to.be.ok;    // truthy

pm.test("Login successful", function () {
    pm.response.to.have.status(200);
    const token = pm.response.json().accessToken;
    pm.environment.set("accessToken", token);
    console.log("Token saved to environment");
});

pm.test("Order created", function () {
    pm.response.to.have.status(201);
    const orderId = pm.response.json().data.id;
    pm.environment.set("orderId", orderId);
    console.log("Order created:", orderId);
});

GET {{baseUrl}}/api/v1/orders/{{orderId}}
Authorization: Bearer {{accessToken}}

pm.test("Order retrieved correctly", function () {
    pm.response.to.have.status(200);
    const order = pm.response.json().data;
    pm.expect(order.id).to.eql(pm.environment.get("orderId"));
});

pm.test("Order deleted", function () {
    pm.response.to.have.status(204);
    // 清理環境變數
    pm.environment.unset("orderId");
});

const schema = {
    type: "object",
    required: ["data", "meta"],
    properties: {
        data: {
            type: "array",
            items: {
                type: "object",
                required: ["id", "name", "status"],
                properties: {
                    id: { type: "string", pattern: "^[A-Z]{2}-\\d+$" },
                    name: { type: "string", minLength: 1 },
                    status: { type: "string", enum: ["ACTIVE", "INACTIVE"] },
                    createdAt: { type: "string", format: "date-time" }
                }
            }
        },
        meta: {
            type: "object",
            required: ["total", "page", "size"],
            properties: {
                total: { type: "integer", minimum: 0 },
                page: { type: "integer", minimum: 1 },
                size: { type: "integer", minimum: 1, maximum: 100 }
            }
        }
    }
};

pm.test("Response matches JSON Schema", function () {
    pm.response.to.have.jsonSchema(schema);
});

pm.test("Pagination is correct", function () {
    const meta = pm.response.json().meta;
    const data = pm.response.json().data;

    pm.expect(meta.page).to.eql(1);
    pm.expect(meta.size).to.eql(20);
    pm.expect(data.length).to.be.at.most(meta.size);
    pm.expect(meta.total).to.be.at.least(data.length);
    pm.expect(meta.totalPages).to.eql(Math.ceil(meta.total / meta.size));
});

pm.test("Error response has correct format", function () {
    pm.response.to.have.status(400);
    const error = pm.response.json();
    pm.expect(error).to.have.property("error");
    pm.expect(error.error).to.have.all.keys("code", "message", "details");
    pm.expect(error.error.code).to.be.a("string");
    pm.expect(error.error.message).to.be.a("string");
    pm.expect(error.error.details).to.be.an("array");
});

pm.test("Response time SLA check", function () {
    // P99 < 500ms
    pm.expect(pm.response.responseTime).to.be.below(500);
});

pm.test("Response time classification", function () {
    const time = pm.response.responseTime;
    if (time < 200) {
        console.log("✅ Excellent: " + time + "ms");
    } else if (time < 500) {
        console.log("⚠️ Acceptable: " + time + "ms");
    } else {
        console.warn("❌ Slow: " + time + "ms");
    }
});

// Package: api-test-helpers

/**
 * 驗證標準成功回應格式
 */
function validateSuccessResponse(statusCode = 200) {
    pm.test(`Status code is ${statusCode}`, function () {
        pm.response.to.have.status(statusCode);
    });

    pm.test("Response time is acceptable", function () {
        pm.expect(pm.response.responseTime).to.be.below(2000);
    });

    pm.test("Content-Type is JSON", function () {
        pm.response.to.have.header("Content-Type");
        pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
    });
}

/**
 * 驗證標準錯誤回應格式
 */
function validateErrorResponse(expectedStatus) {
    pm.test(`Status code is ${expectedStatus}`, function () {
        pm.response.to.have.status(expectedStatus);
    });

    pm.test("Error response has standard format", function () {
        const body = pm.response.json();
        pm.expect(body).to.have.property("error");
        pm.expect(body.error).to.have.property("code");
        pm.expect(body.error).to.have.property("message");
    });
}

module.exports = { validateSuccessResponse, validateErrorResponse };

const { validateSuccessResponse, validateErrorResponse } = pm.require("api-test-helpers");

// 使用共用函式
validateSuccessResponse(200);

// 額外的自訂測試
pm.test("Response contains orders", function () {
    pm.expect(pm.response.json().data).to.be.an("array").and.to.not.be.empty;
});

// 跳轉到指定請求
pm.execution.setNextRequest("Create Order");

// 跳過後續所有請求（結束執行）
pm.execution.setNextRequest(null);

// 條件式跳轉
if (pm.response.code === 401) {
    pm.execution.setNextRequest("Login");  // Token 過期，重新登入
} else if (pm.response.code === 200) {
    pm.execution.setNextRequest("Verify Order");
}

// 跳過當前請求（Pre-request Script 中使用）
pm.execution.skipRequest();

// 取得當前迭代的預期值
const expectedStatus = parseInt(pm.iterationData.get("expectedStatus"));
const expectedMessage = pm.iterationData.get("expectedMessage");
const testEmail = pm.iterationData.get("email");

pm.test(`[${testEmail}] Status ${expectedStatus}`, function () {
    pm.response.to.have.status(expectedStatus);
});

pm.test(`[${testEmail}] Message: ${expectedMessage}`, function () {
    const body = pm.response.json();
    pm.expect(body.message).to.include(expectedMessage);
});

📋 Collection: Order Integration Tests
├── 📁 Setup
│   ├── POST /auth/login              → 取得 Token
│   └── POST /products                → 建立測試商品
├── 📁 Happy Path
│   ├── POST /orders                  → 建立訂單
│   ├── GET /orders/:id               → 查詢訂單
│   ├── PUT /orders/:id/status        → 更新狀態
│   └── GET /orders/:id/history       → 查詢歷程
├── 📁 Error Cases
│   ├── POST /orders (invalid body)   → 400 驗證
│   ├── GET /orders/nonexistent       → 404 驗證
│   └── DELETE /orders/:id (no auth)  → 401 驗證
└── 📁 Cleanup
    ├── DELETE /orders/:id            → 刪除測試訂單
    └── DELETE /products/:id          → 刪除測試商品

# Windows（PowerShell）
powershell -Command "iwr 'https://dl-cli.pstmn.io/install/win64.ps1' -useb | iex"

# macOS
curl -o- "https://dl-cli.pstmn.io/install/osx_arm64.sh" | sh

# Linux
curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

# 使用 API Key 登入（CI/CD 環境推薦）
postman login --with-api-key PMAK-xxxxxxxxxxxxxxxxxxxxxxxx

# API Key 取得方式：Postman Settings → API Keys → Generate API Key

# 基本執行
postman collection run <collection-id>

# 指定環境
postman collection run <collection-id> -e <environment-id>

# 指定迭代次數與資料檔案
postman collection run <collection-id> \
    -e <environment-id> \
    --iteration-count 5 \
    --iteration-data test-data.csv

# 指定資料夾（僅執行部分測試）
postman collection run <collection-id> \
    --folder "Happy Path"

# 輸出報告
postman collection run <collection-id> \
    -e <environment-id> \
    --reporter-cli \
    --reporter-json --reporter-json-export results.json

# 安裝
npm install -g newman
npm install -g newman-reporter-htmlextra

# 執行
newman run collection.json \
    -e environment.json \
    --reporters cli,htmlextra \
    --reporter-htmlextra-export report.html

# 從 Postman API 直接執行
newman run "https://api.getpostman.com/collections/<id>?apikey=<key>" \
    -e "https://api.getpostman.com/environments/<id>?apikey=<key>"

# .github/workflows/api-tests.yml
name: API Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 */6 * * *'  # 每 6 小時執行一次

jobs:
  api-tests:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Postman CLI
        run: |
          curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

      - name: Login to Postman CLI
        run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}

      - name: Run API Tests
        run: |
          postman collection run ${{ vars.POSTMAN_COLLECTION_ID }} \
            -e ${{ vars.POSTMAN_ENVIRONMENT_ID }} \
            --reporter-cli \
            --reporter-json --reporter-json-export results.json

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-results
          path: results.json

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v2
        with:
          webhook: ${{ secrets.SLACK_WEBHOOK }}
          payload: |
            {
              "text": "❌ API Tests failed on ${{ github.ref_name }}"
            }

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        POSTMAN_API_KEY = credentials('postman-api-key')
    }
    
    stages {
        stage('Install Postman CLI') {
            steps {
                sh 'curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh'
            }
        }
        
        stage('Run API Tests') {
            steps {
                sh '''
                    postman login --with-api-key ${POSTMAN_API_KEY}
                    postman collection run ${POSTMAN_COLLECTION_ID} \
                        -e ${POSTMAN_ENVIRONMENT_ID} \
                        --reporter-json --reporter-json-export results.json
                '''
            }
            post {
                always {
                    archiveArtifacts artifacts: 'results.json'
                }
                failure {
                    slackSend channel: '#api-alerts',
                        message: "API Tests failed: ${env.BUILD_URL}"
                }
            }
        }
    }
}

# azure-pipelines.yml
trigger:
  branches:
    include:
      - main
      - develop

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: CmdLine@2
    displayName: 'Install Postman CLI'
    inputs:
      script: 'curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh'

  - task: CmdLine@2
    displayName: 'Run API Tests'
    inputs:
      script: |
        postman login --with-api-key $(POSTMAN_API_KEY)
        postman collection run $(POSTMAN_COLLECTION_ID) \
          -e $(POSTMAN_ENVIRONMENT_ID) \
          --reporter-json --reporter-json-export $(Build.ArtifactStagingDirectory)/results.json
    env:
      POSTMAN_API_KEY: $(PostmanApiKey)

  - task: PublishBuildArtifacts@1
    displayName: 'Publish Results'
    condition: always()
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'api-test-results'

openapi: 3.1.0
info:
  title: Order API
  version: 2.0.0
  description: 訂單管理服務 API
servers:
  - url: https://api.company.com/v2
    description: Production
  - url: https://sit-api.company.com/v2
    description: SIT
paths:
  /orders:
    get:
      summary: 查詢訂單列表
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [ACTIVE, COMPLETED, CANCELLED]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
    post:
      summary: 建立訂單
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: 建立成功
components:
  schemas:
    OrderListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Order:
      type: object
      required: [id, status, totalAmount]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [ACTIVE, COMPLETED, CANCELLED]
        totalAmount:
          type: number
          format: double

// Pre-request Script：開發階段自動切換 Mock
const useMock = pm.environment.get("useMock");
if (useMock === "true") {
    pm.request.url = pm.request.url.toString()
        .replace(pm.environment.get("baseUrl"), pm.environment.get("mockUrl"));
}

📁 Git Repository: api-collections
├── collections/
│   ├── order-api-v2.json
│   └── order-api-v1.json
├── environments/
│   ├── dev.json
│   ├── sit.json
│   └── uat.json
└── schemas/
    └── order-api-v2.yaml  (OpenAPI)

[Login] → [Select Token] → [Create Order] → [Select Order ID]
                                                     │
                                             ┌───────┴───────┐
                                             ▼               ▼
                                     [Get Order]      [List Orders]
                                             │               │
                                             ▼               ▼
                                     [Verify Status]  [Verify In List]
                                             │               │
                                             └───────┬───────┘
                                                     ▼
                                             [Delete Order]
                                                     │
                                                     ▼
                                              [Output Results]

使用者輸入：「驗證回應是否為有效的訂單列表，包含分頁資訊，
          每筆訂單都有 id、status 和 totalAmount」

Postman AI 產出：
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has pagination metadata", function () {
    const meta = pm.response.json().meta;
    pm.expect(meta).to.have.property("total");
    pm.expect(meta).to.have.property("page");
    pm.expect(meta).to.have.property("size");
});

pm.test("Each order has required fields", function () {
    const orders = pm.response.json().data;
    orders.forEach(order => {
        pm.expect(order).to.have.property("id");
        pm.expect(order).to.have.property("status");
        pm.expect(order).to.have.property("totalAmount");
    });
});

// MCP Server 設定（VS Code settings.json）
{
  "mcp": {
    "servers": {
      "postman": {
        "command": "npx",
        "args": ["-y", "@anthropic/postman-mcp-server"],
        "env": {
          "POSTMAN_API_KEY": "PMAK-xxxxxxxx"
        }
      }
    }
  }
}

📋 Collection: Order API v2 (Team)
        │
        ├── 🍴 Fork → Order API v2 (Alice's Workspace)
        │       │ ← Alice 修改
        │       └── 📤 Create Pull Request
        │
        └── 🍴 Fork → Order API v2 (Bob's Workspace)
                │ ← Bob 修改
                └── 📤 Create Pull Request

📁 Team Workspaces
├── 🏢 [Project] Order Service
│   ├── 📋 Order API v2 (Source of Truth)
│   ├── 📋 Order Integration Tests
│   ├── 📋 Order Performance Tests
│   ├── 🌐 Environments (dev / sit / uat / prod)
│   ├── 🎭 Mock Server
│   ├── 📡 Monitor: Health Check
│   └── 📖 API: Order API (OpenAPI)
│
├── 🏢 [Project] User Service
│   └── ...
│
├── 🧪 [Shared] Test Utilities
│   ├── 📋 Common Test Scripts
│   └── 📦 Package Library
│
└── 📚 [Shared] API Standards & Templates
    ├── 📋 API Template Collection
    └── 📄 API Design Guidelines

# 自訂 Governance Rule
rules:
  company-api-standards:
    - rule: require-correlation-id
      description: "所有 API 必須支援 X-Correlation-ID Header"
      severity: error
      given: "$.paths.*.*.parameters"
      then:
        function: schema
        functionOptions:
          schema:
            type: array
            contains:
              properties:
                name:
                  const: "X-Correlation-ID"

// 健康檢查腳本
pm.test("API is healthy", function () {
    pm.response.to.have.status(200);
});

pm.test("Response time SLA (< 1s)", function () {
    pm.expect(pm.response.responseTime).to.be.below(1000);
});

pm.test("Database connectivity", function () {
    const health = pm.response.json();
    pm.expect(health.database).to.eql("UP");
});

pm.test("External service connectivity", function () {
    const health = pm.response.json();
    pm.expect(health.externalServices.payment).to.eql("UP");
    pm.expect(health.externalServices.notification).to.eql("UP");
});

# 認證：所有請求需包含 API Key
# Header: X-Api-Key: PMAK-xxxxxxxx

# 列出所有 Collection
GET /collections

# 取得特定 Collection
GET /collections/{collection_id}

# 列出所有 Environment
GET /environments

# 取得特定 Environment
GET /environments/{environment_id}

# 列出所有 Workspace
GET /workspaces

# 建立 Collection
POST /collections
{
  "collection": {
    "info": {
      "name": "New Collection",
      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    }
  }
}

# GitHub Actions：部署後觸發 Postman 測試
- name: Trigger Postman API Tests
  run: |
    curl -X POST "https://newman-api.getpostman.com/run/${{ secrets.POSTMAN_WEBHOOK_ID }}" \
      -H "Content-Type: application/json" \
      -d '{"environment": "${{ vars.POSTMAN_ENVIRONMENT_ID }}"}'

// Post-response Script
const response = pm.response.json();
const currentPage = parseInt(pm.environment.get("currentPage") || "1");
const totalPages = response.meta.totalPages;

if (currentPage < totalPages) {
    pm.environment.set("currentPage", String(currentPage + 1));
    pm.execution.setNextRequest(pm.info.requestName); // 重複執行自己
} else {
    pm.environment.unset("currentPage");
    pm.execution.setNextRequest(null); // 結束
}

// ===== 變數操作 =====
pm.variables.get("key")                    // Local 變數
pm.variables.set("key", "value")
pm.environment.get("key")                  // Environment 變數
pm.environment.set("key", "value")
pm.environment.unset("key")
pm.environment.name                        // 當前環境名稱
pm.collectionVariables.get("key")          // Collection 變數
pm.collectionVariables.set("key", "value")
pm.globals.get("key")                      // Global 變數
pm.globals.set("key", "value")
pm.iterationData.get("key")               // Data 檔案變數
pm.variables.replaceIn("{{var}}")          // 解析變數字串

// ===== 請求資訊 =====
pm.request.url                             // 完整 URL
pm.request.method                          // HTTP Method
pm.request.headers                         // Headers
pm.request.body                            // Request Body
pm.info.requestName                        // 請求名稱
pm.info.iteration                          // 當前迭代次數
pm.info.iterationCount                     // 總迭代次數
pm.info.requestId                          // 請求 ID

// ===== 回應資訊 =====
pm.response.code                           // Status Code (number)
pm.response.status                         // Status Text ("OK")
pm.response.json()                         // 解析為 JSON
pm.response.text()                         // 原始文字
pm.response.headers                        // Response Headers
pm.response.responseTime                   // 回應時間 (ms)
pm.response.responseSize                   // 回應大小 (bytes)

// ===== 測試 =====
pm.test("name", function () { ... })       // 定義測試
pm.expect(value).to.eql(expected)          // BDD 斷言
pm.response.to.have.status(200)            // Status 斷言
pm.response.to.have.header("key")          // Header 斷言
pm.response.to.have.jsonSchema(schema)     // Schema 斷言

// ===== 執行控制 =====
pm.execution.setNextRequest("name")        // 跳轉請求
pm.execution.setNextRequest(null)          // 結束執行
pm.execution.skipRequest()                 // 跳過當前請求

// ===== 發送額外請求 =====
pm.sendRequest(options, callback)          // 發送請求
pm.sendRequest("https://...", (err, res) => { ... })

// ===== Cookie =====
pm.cookies.get("name")                     // 取得 Cookie
pm.cookies.has("name")                     // 是否存在

// ===== 視覺化 =====
pm.visualizer.set(template, data)          // 自訂視覺化

// ===== 內建函式庫 =====
const crypto = require('crypto-js')        // 加密
const moment = require('moment')           // 日期（Legacy）
const _ = require('lodash')                // 工具函式
const uuid = require('uuid')               // UUID 產生
const xml2js = require('xml2js')           // XML 解析
const cheerio = require('cheerio')         // HTML 解析
const tv4 = require('tv4')                 // JSON Schema（Legacy）
const ajv = require('ajv')                 // JSON Schema（推薦）

// ===== 相等 =====
expect(a).to.eql(b)           // 深度相等（推薦）
expect(a).to.equal(b)         // 嚴格相等 ===
expect(a).to.not.eql(b)       // 不等

// ===== 類型 =====
expect(a).to.be.a("string")
expect(a).to.be.an("array")
expect(a).to.be.a("number")
expect(a).to.be.an("object")
expect(a).to.be.a("boolean")
expect(a).to.be.null
expect(a).to.be.undefined
expect(a).to.be.NaN

// ===== 布林 =====
expect(a).to.be.true
expect(a).to.be.false
expect(a).to.be.ok             // truthy
expect(a).to.not.be.ok         // falsy

// ===== 數值比較 =====
expect(a).to.be.above(n)       // >
expect(a).to.be.below(n)       // <
expect(a).to.be.at.least(n)    // >=
expect(a).to.be.at.most(n)     // <=
expect(a).to.be.within(m, n)   // m <= a <= n
expect(a).to.be.closeTo(n, d)  // |a - n| <= d

// ===== 字串 =====
expect(s).to.include("sub")
expect(s).to.match(/regex/)
expect(s).to.have.string("sub")

// ===== 陣列 =====
expect(arr).to.include(item)
expect(arr).to.have.members([a, b])
expect(arr).to.include.members([a])
expect(arr).to.have.lengthOf(n)
expect(arr).to.be.empty
expect(arr).to.not.be.empty
expect(arr).to.have.length.above(0)

// ===== 物件 =====
expect(obj).to.have.property("key")
expect(obj).to.have.property("key", "val")
expect(obj).to.have.all.keys("a", "b")
expect(obj).to.have.any.keys("a", "b")
expect(obj).to.have.nested.property("a.b.c")
expect(obj).to.deep.include({ key: "val" })

□ 安裝 Postman 桌面版（或使用網頁版 + Agent）
□ 註冊 Postman 帳號並登入
□ 加入團隊 Workspace
□ 熟悉介面：Sidebar、Workbench、Console、Footer Bar
□ 建立第一個 GET 請求（呼叫公開 API）
□ 了解 Collection 與 Folder 概念，建立第一個 Collection
□ 建立 Environment（dev）並設定 baseUrl 變數
□ 使用 {{baseUrl}} 發送請求
□ 撰寫第一個 Post-response Script（驗證 Status Code）
□ 使用 Console 檢視請求 / 回應詳情
□ 匯入團隊現有的 Collection
□ Fork 團隊 Collection 進行修改
□ 建立 Pull Request 提交變更
□ 了解 Postman Vault 並設定敏感資料
□ 執行 Collection Runner 批次測試
□ 閱讀團隊 API 測試規範文件

□ 功能測試
  □ 所有 CRUD 操作正常（200 / 201 / 204）
  □ 正確的 Request Body 格式與必填欄位
  □ Query Parameters 篩選 / 排序 / 分頁正確
  □ Path Parameters 正確解析
  □ Response Body 結構符合規格（JSON Schema）

□ 錯誤處理
  □ 必填欄位缺失 → 400 Bad Request
  □ 無效資料格式 → 400 Bad Request
  □ 未認證 → 401 Unauthorized
  □ 權限不足 → 403 Forbidden
  □ 資源不存在 → 404 Not Found
  □ 重複建立 → 409 Conflict
  □ 錯誤回應格式統一（error.code + error.message）

□ 認證與授權
  □ 無 Token → 401
  □ 過期 Token → 401
  □ 無效 Token → 401
  □ 錯誤角色 → 403
  □ Token 刷新流程正常

□ 效能
  □ 回應時間 < SLA 閾值
  □ 大量資料查詢效能可接受
  □ 分頁查詢效能穩定

□ 邊界條件
  □ 空陣列回應正確（data: [], meta.total: 0）
  □ 超長字串處理
  □ 特殊字元（中文、emoji、HTML entities）
  □ 數值邊界（0、負數、最大值）
  □ 日期格式（ISO 8601）

□ 安全性
  □ SQL Injection 防護（在參數中嘗試 ' OR 1=1）
  □ XSS 防護（在輸入中嘗試 <script>）
  □ 敏感資料不在 URL 中傳遞
  □ 回應不洩漏伺服器資訊（Server Header）
  □ CORS 設定正確

□ 帳號與存取
  □ 所有成員使用 SSO 登入（Enterprise）
  □ 已離職人員已從團隊移除
  □ 最小權限原則：依角色分配權限
  □ 定期審查成員權限

□ 敏感資料管理
  □ API Key / Token / Password 存放在 Postman Vault
  □ Environment Variables 的 Initial Value 不含敏感資料
  □ Secret Scanner 已啟用
  □ 定期審查 Secret Scanner 報告
  □ CI/CD 的 API Key 存放在 Pipeline Secret

□ Collection 安全
  □ Production Collection 設定唯讀（Viewer 權限）
  □ Fork → PR → Merge 流程執行中
  □ 不在 Description 或 README 中放置密碼

□ 網路安全
  □ SSL 驗證已啟用（生產環境）
  □ 企業 CA 憑證已正確安裝
  □ Proxy 設定正確且安全
  □ mTLS 憑證設定正確（如適用）

□ 稽核與合規
  □ Audit Log 已啟用（Enterprise）
  □ 稽核日誌匯出至 SIEM
  □ API Governance Rules 已設定
  □ 定期合規審查