name: newman description: 通过Newman CLI使用Postman集合进行自动化API测试。当用户请求API测试、集合执行、自动化测试、CI/CD集成，或提及“Postman”、“Newman”、“API测试”、“运行集合”或“自动化测试”时使用。

Newman - Postman命令行运行器

Newman是Postman的命令行集合运行器。直接从命令行运行和测试Postman集合，提供强大的报告、环境管理和CI/CD集成功能。

快速开始

安装

# 全局安装（推荐）
npm install -g newman

# 项目内安装
npm install --save-dev newman

# 验证
newman --version

基本执行

# 运行集合
newman run collection.json

# 使用环境变量文件
newman run collection.json -e environment.json

# 使用全局变量文件
newman run collection.json -g globals.json

# 组合使用
newman run collection.json -e env.json -g globals.json -d data.csv

核心工作流

1. 从Postman桌面版导出

在Postman中：

集合 → 点击“…” → 导出
选择“Collection v2.1”（推荐）
保存为 collection.json

环境变量：

环境 → 点击“…” → 导出
保存为 environment.json

2. 运行测试

# 基本运行
newman run collection.json

# 详细输出
newman run collection.json --verbose

# 出错时立即停止
newman run collection.json --bail

# 自定义超时（30秒）
newman run collection.json --timeout-request 30000

3. 数据驱动测试

CSV格式：

username,password
user1,pass1
user2,pass2

运行：

newman run collection.json -d test_data.csv --iteration-count 2

4. 报告器

# 仅命令行（默认）
newman run collection.json

# HTML报告
newman run collection.json --reporters cli,html --reporter-html-export report.html

# JSON导出
newman run collection.json --reporters cli,json --reporter-json-export results.json

# JUnit（用于CI）
newman run collection.json --reporters cli,junit --reporter-junit-export junit.xml

# 多个报告器
newman run collection.json --reporters cli,html,json,junit \
  --reporter-html-export ./reports/newman.html \
  --reporter-json-export ./reports/newman.json \
  --reporter-junit-export ./reports/newman.xml

5. 安全最佳实践

❌ 切勿在集合中硬编码密钥！

使用环境变量：

# 导出敏感变量
export API_KEY="your-secret-key"
export DB_PASSWORD="your-db-pass"

# Newman自动从环境加载
newman run collection.json -e environment.json

# 或直接传递
newman run collection.json --env-var "API_KEY=secret" --env-var "DB_PASSWORD=pass"

在Postman集合测试中：

// 在请求中使用 {{API_KEY}}
pm.request.headers.add({key: 'Authorization', value: `Bearer {{API_KEY}}`});

// 在脚本中访问
const apiKey = pm.environment.get("API_KEY");

环境文件（environment.json）：

{
  "name": "生产环境",
  "values": [
    {"key": "BASE_URL", "value": "https://api.example.com", "enabled": true},
    {"key": "API_KEY", "value": "{{$processEnvironment.API_KEY}}", "enabled": true}
  ]
}

Newman会将 {{$processEnvironment.API_KEY}} 替换为环境变量。

常见用例

CI/CD集成

查看 references/ci-cd-examples.md 获取GitHub Actions、GitLab CI和Jenkins示例。

自动化回归测试

#!/bin/bash
# scripts/run-api-tests.sh

set -e

echo "运行API测试..."

newman run collections/api-tests.json \
  -e environments/staging.json \
  --reporters cli,html,junit \
  --reporter-html-export ./test-results/newman.html \
  --reporter-junit-export ./test-results/newman.xml \
  --bail \
  --color on

echo "测试完成。报告：./test-results/newman.html"

负载测试

# 高迭代次数运行
newman run collection.json \
  -n 100 \
  --delay-request 100 \
  --timeout-request 5000 \
  --reporters cli,json \
  --reporter-json-export load-test-results.json

并行执行

# 安装并行运行器
npm install -g newman-parallel

# 并行运行集合
newman-parallel -c collection1.json,collection2.json,collection3.json \
  -e environment.json \
  --reporters cli,html

高级功能

自定义脚本

预请求脚本（在Postman中）：

// 生成动态值
pm.environment.set("timestamp", Date.now());
pm.environment.set("nonce", Math.random().toString(36).substring(7));

测试脚本（在Postman中）：

// 状态码检查
pm.test("状态码为200", function() {
    pm.response.to.have.status(200);
});

// 响应体验证
pm.test("响应包含用户ID", function() {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('user_id');
});

// 响应时间检查
pm.test("响应时间 < 500ms", function() {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// 从响应设置变量
pm.environment.set("user_token", pm.response.json().token);

SSL/TLS配置

# 禁用SSL验证（仅开发！）
newman run collection.json --insecure

# 自定义CA证书
newman run collection.json --ssl-client-cert-list cert-list.json

# 客户端证书
newman run collection.json \
  --ssl-client-cert client.pem \
  --ssl-client-key key.pem \
  --ssl-client-passphrase "secret"

错误处理

# 出错时继续
newman run collection.json --suppress-exit-code

# 快速失败
newman run collection.json --bail

# 包装器中的自定义错误处理
#!/bin/bash
newman run collection.json -e env.json
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
    echo "测试失败！退出码：$EXIT_CODE"
    # 发送警报、回滚部署等
    exit 1
fi

故障排除

集合未找到：

使用绝对路径：newman run /完整路径/to/collection.json
检查文件权限：ls -la collection.json

环境变量未加载：

验证语法：{{$processEnvironment.VAR_NAME}}
检查导出：echo $VAR_NAME
使用 --env-var 标志作为备用方案

超时错误：

增加超时：--timeout-request 60000（60秒）
检查网络连接
验证API端点可达

SSL错误：

开发环境：临时使用 --insecure
生产环境：使用 --ssl-extra-ca-certs 添加CA证书

内存问题（大型集合）：

减少迭代次数
将集合拆分为更小的部分
增加Node堆内存：NODE_OPTIONS=--max-old-space-size=4096 newman run ...

最佳实践

版本控制：将集合和环境存储在Git中
环境分离：为开发/预发布/生产环境使用单独的文件
密钥管理：使用环境变量，切勿提交密钥
有意义的名称：使用描述性的集合和文件夹名称
测试原子性：每个请求应测试一个特定内容
断言：为每个请求添加全面的测试脚本
文档：使用Postman描述提供上下文
CI集成：在CI流水线中为每个PR运行Newman
报告：存档HTML报告用于历史分析
超时：为生产API设置合理的超时值

参考

CI/CD示例：查看 references/ci-cd-examples.md
高级模式：查看 references/advanced-patterns.md
官方文档：https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/