什么是 Newman - Postman 命令行执行器？

Newman 是 Postman 官方提供的命令行集合执行器，旨在让开发人员能够直接从终端或在自动化环境中运行和测试 API 集合。通过利用 Newman 等 Openclaw 技能，团队可以从手动 API 验证过渡到强大的自动化测试框架，确保开发、测试和生产环境的一致性。

它基于 Node.js 构建，与 Postman 桌面应用的执行引擎完全兼容，这意味着您的预请求脚本和测试断言将完全按照预期运行。此技能是优先考虑 API 优先设计和持续集成的现代开发工作流的基石。

下载入口:https://github.com/openclaw/skills/tree/main/skills/1999azzar/newman

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Newman - Postman 命令行执行器 应用场景

• 在开发过程中对 API 端点运行自动化回归测试。
• 将 API 测试套件集成到 GitHub Actions、GitLab CI 或 Jenkins 等 CI/CD 流水线中。
• 使用外部 CSV 或 JSON 文件执行数据驱动测试，以验证多种场景。
• 生成可共享的 HTML 或 JUnit 报告，用于质量保证和利益相关者审查。
• 通过运行高迭代次数和特定延迟的集合来进行基础负载测试。

1. 从 Postman 桌面应用程序中将您的 API 请求和测试脚本导出为 v2.1 集合 JSON 文件。
2. 可选：将环境变量导出为环境 JSON 文件，以管理特定阶段的数据。
3. 使用 Newman CLI 执行集合，传入 JSON 文件和任何所需的数据源。
4. Newman 处理集合中的每个请求，执行预请求脚本并验证测试断言。
5. 该工具在终端中生成实时反馈，并以您喜欢的格式（HTML、JSON 或 XML）保存详细报告。

Newman - Postman 命令行执行器 配置指南

要开始使用此技能，请确保您的系统中已安装 Node.js。然后您可以全局安装执行器或在特定项目中安装。

# 通过 npm 全局安装 Newman
npm install -g newman

# 验证安装
newman --version

# 在本地运行集合文件
newman run your-collection.json

Newman - Postman 命令行执行器 数据架构与分类体系

Newman 通过几种专门的文件格式管理数据，以确保 Openclaw Skills 工作流中的便携性和安全性：

name: newman
description: Automated API testing with Postman collections via Newman CLI. Use when user requests API testing, collection execution, automated testing, CI/CD integration, or mentions "Postman", "Newman", "API tests", "run collection", or "automated testing".

Newman - Postman CLI Runner

Newman is the command-line Collection Runner for Postman. Run and test Postman collections directly from the command line with powerful reporting, environment management, and CI/CD integration.

Quick Start

Installation

# Global install (recommended)
npm install -g newman

# Project-specific
npm install --save-dev newman

# Verify
newman --version

Basic Execution

# Run collection
newman run collection.json

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

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

# Combined
newman run collection.json -e env.json -g globals.json -d data.csv

Core Workflows

1. Export from Postman Desktop

In Postman:

1. Collections → Click "..." → Export
2. Choose "Collection v2.1" (recommended)
3. Save as collection.json

Environment:

1. Environments → Click "..." → Export
2. Save as environment.json

2. Run Tests

# Basic run
newman run collection.json

# With detailed output
newman run collection.json --verbose

# Fail on errors
newman run collection.json --bail

# Custom timeout (30s)
newman run collection.json --timeout-request 30000

3. Data-Driven Testing

CSV format:

username,password
user1,pass1
user2,pass2

Run:

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

4. Reporters

# CLI only (default)
newman run collection.json

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

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

# JUnit (for CI)
newman run collection.json --reporters cli,junit --reporter-junit-export junit.xml

# Multiple reporters
newman run collection.json --reporters cli,html,json,junit r
  --reporter-html-export ./reports/newman.html r
  --reporter-json-export ./reports/newman.json r
  --reporter-junit-export ./reports/newman.xml

5. Security Best Practices

? NEVER hardcode secrets in collections!

Use environment variables:

# Export sensitive vars
export API_KEY="your-secret-key"
export DB_PASSWORD="your-db-pass"

# Newman auto-loads from env
newman run collection.json -e environment.json

# Or pass directly
newman run collection.json --env-var "API_KEY=secret" --env-var "DB_PASSWORD=pass"

In Postman collection tests:

// Use {{API_KEY}} in requests
pm.request.headers.add({key: 'Authorization', value: `Bearer {{API_KEY}}`});

// Access in scripts
const apiKey = pm.environment.get("API_KEY");

Environment file (environment.json):

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

Newman will replace {{$processEnvironment.API_KEY}} with the environment variable.

Common Use Cases

CI/CD Integration

See references/ci-cd-examples.md for GitHub Actions, GitLab CI, and Jenkins examples.

Automated Regression Testing

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

set -e

echo "Running API tests..."

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

echo "Tests completed. Report: ./test-results/newman.html"

Load Testing

# Run with high iteration count
newman run collection.json r
  -n 100 r
  --delay-request 100 r
  --timeout-request 5000 r
  --reporters cli,json r
  --reporter-json-export load-test-results.json

Parallel Execution

# Install parallel runner
npm install -g newman-parallel

# Run collections in parallel
newman-parallel -c collection1.json,collection2.json,collection3.json r
  -e environment.json r
  --reporters cli,html

Advanced Features

Custom Scripts

Pre-request Script (in Postman):

// Generate dynamic values
pm.environment.set("timestamp", Date.now());
pm.environment.set("nonce", Math.random().toString(36).substring(7));

Test Script (in Postman):

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

// Response body validation
pm.test("Response has user ID", function() {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('user_id');
});

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

// Set variable from response
pm.environment.set("user_token", pm.response.json().token);

SSL/TLS Configuration

# Disable SSL verification (dev only!)
newman run collection.json --insecure

# Custom CA certificate
newman run collection.json --ssl-client-cert-list cert-list.json

# Client certificates
newman run collection.json r
  --ssl-client-cert client.pem r
  --ssl-client-key key.pem r
  --ssl-client-passphrase "secret"

Error Handling

# Continue on errors
newman run collection.json --suppress-exit-code

# Fail fast
newman run collection.json --bail

# Custom error handling in wrapper
#!/bin/bash
newman run collection.json -e env.json
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
    echo "Tests failed! Exit code: $EXIT_CODE"
    # Send alert, rollback deployment, etc.
    exit 1
fi

Troubleshooting

Collection not found:

• Use absolute paths: newman run /full/path/to/collection.json
• Check file permissions: ls -la collection.json

Environment variables not loading:

• Verify syntax: {{$processEnvironment.VAR_NAME}}
• Check export: echo $VAR_NAME
• Use --env-var flag as fallback

Timeout errors:

• Increase timeout: --timeout-request 60000 (60s)
• Check network connectivity
• Verify API endpoint is reachable

SSL errors:

• Development: Use --insecure temporarily
• Production: Add CA cert with --ssl-extra-ca-certs

Memory issues (large collections):

• Reduce iteration count
• Split collection into smaller parts
• Increase Node heap: NODE_OPTIONS=--max-old-space-size=4096 newman run ...

Best Practices

1. Version Control: Store collections and environments in Git
2. Environment Separation: Separate files for dev/staging/prod
3. Secret Management: Use environment variables, never commit secrets
4. Meaningful Names: Use descriptive collection and folder names
5. Test Atomicity: Each request should test one specific thing
6. Assertions: Add comprehensive test scripts to every request
7. Documentation: Use Postman descriptions for context
8. CI Integration: Run Newman in CI pipeline for every PR
9. Reports: Archive HTML reports for historical analysis
10. Timeouts: Set reasonable timeout values for production APIs

References

• CI/CD Examples: See references/ci-cd-examples.md
• Advanced Patterns: See references/advanced-patterns.md
• Official Docs: https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/