Package Exports

collection-runner-cli
collection-runner-cli/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (collection-runner-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

CollectionRunner CLI

A modern CLI tool to run Postman collections with Newman, collect detailed execution metrics, generate beautiful HTML reports with interactive charts, and send notifications to Telegram.

🔒 Enterprise-Grade Security | ✅ Production Ready | 📊 Advanced Metrics | 🎨 Beautiful Reports

Installation

Recommended: Global Installation (CLI)

npm install -g collection-runner-cli

After installation, the collection-runner command will be available globally.

Local Installation

npm install collection-runner-cli

From Source

git clone https://github.com/yourusername/collection-runner-cli.git
cd collection-runner-cli
npm install
npm link

Verify Installation

collection-runner --help

Features

✨ Key Features:

🚀 Run Postman collections via CLI with Newman API
📊 Collect detailed execution metrics (response times, status codes, assertions)
🎨 Generate beautiful, modern HTML reports with Chart.js visualizations
📈 Interactive charts: assertions pie charts, request status distribution, response times, failures
💬 Telegram bot integration for automatic report notifications
📱 Responsive design - works on desktop and mobile
⚡ Single standalone HTML file (no external dependencies)
🛡️ Comprehensive error handling and validation

Installation

# Clone or navigate to the project directory
cd collection-runner

# Install dependencies
npm install

# Create global CLI command (optional but recommended)
npm link

# (Optional) Verify security
npm audit

Security Status

✅ Production Ready
📊 0 Critical Vulnerabilities | 0 High Vulnerabilities | 3 Moderate (transitive)

See SECURITY_REPORT.md for detailed security audit and SECURITY_GUIDELINES.md for best practices.

Quick Start

# Save credentials securely (one-time setup)
collection-runner config set telegram-token YOUR_BOT_TOKEN
collection-runner config set telegram-chat-id YOUR_CHAT_ID

# Run collection with HTML report
collection-runner --collection ./examples/sample_collection.json

# Run with environment file
collection-runner --collection ./my_collection.json --env ./my_env.json

# Multiple iterations
collection-runner --collection ./my_collection.json --iterations 3

# Custom report location
collection-runner --collection ./my_collection.json --report-dir ./reports --report-name my_test

# With Telegram notifications (uses saved credentials)
collection-runner --collection ./my_collection.json

# See all options
collection-runner --help

CLI Options

Option	Type	Required	Description
`--collection <path>`	string	✅ Yes	Path to Postman collection JSON file
`--env <path>`	string	❌ No	Path to Postman environment JSON file
`--iterations <number>`	number	❌ No	Number of iterations (default: 1)
`--telegram-token <token>`	string	❌ No	Telegram bot token for notifications
`--telegram-chat-id <id>`	string	❌ No	Telegram chat ID (required if token provided)
`--report-dir <path>`	string	❌ No	Report output directory (default: `./reports`)
`--report-name <name>`	string	❌ No	Report file base name (default: `report-<timestamp>`)
`--verbose`	flag	❌ No	Enable verbose logging
`--help`	flag	❌ No	Show help message

HTML Report Features

Overview Section

Collection name and overall status (PASSED/FAILED)
Key metrics cards: total requests, failed requests, assertions, duration
Execution timeline with start/end times

Analytics Charts

Request Status Distribution - Doughnut chart showing passed vs failed requests
Assertion Results - Doughnut chart showing passed vs failed assertions
Top 10 Slowest Requests - Horizontal bar chart with response times
Failed Requests - Bar chart showing failure counts per endpoint

Request Details Table

Request name, HTTP method, URL, status code
Response duration in milliseconds
Assertion pass/fail counts
Collapsible rows with detailed error messages and assertion details
Color-coded rows (green for pass, red for fail)

Telegram Integration

To enable Telegram notifications:

Create a Telegram Bot
- Chat with @BotFather on Telegram
- Follow instructions to create a new bot
- Copy your bot token
Get Your Chat ID
- Chat with your bot
- Visit: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
- Find your chat ID in the response

Secure Configuration (Recommended)

# Store credentials securely - one time only!
collection-runner config set telegram-token YOUR_BOT_TOKEN
collection-runner config set telegram-chat-id YOUR_CHAT_ID

# Now run collections - credentials are automatically used
collection-runner --collection ./my_collection.json

Run CollectionRunner with notifications

collection-runner --collection ./my_collection.json
# Uses saved token and chat ID from config

Configuration Management

Manage your CollectionRunner settings securely:

# Save settings
collection-runner config set telegram-token YOUR_TOKEN
collection-runner config set telegram-chat-id YOUR_CHAT_ID
collection-runner config set report-dir ./my_reports

# View settings (tokens are masked)
collection-runner config show

# Get specific value
collection-runner config get telegram-token

# Clear specific value
collection-runner config clear telegram-token

# Reset all to defaults
collection-runner config reset

Storage Location:

Linux/Mac: ~/.collection-runner/config.json
Windows: %USERPROFILE%\.collection-runner\config.json

⚠️ Important: Always use config manager for credentials, never pass tokens as command-line arguments!

Project Structure

collection-runner/
├── bin/
│   └── collection-runner.js      # CLI entry point with shebang
├── src/
│   ├── index.js                  # Main orchestrator
│   ├── newmanRunner.js           # Newman API wrapper
│   ├── reportGenerator.js        # HTML report generator
│   ├── telegramNotifier.js       # Telegram bot integration
│   └── utils/
│       ├── argParser.js          # CLI argument parsing
│       ├── logger.js             # Logging utilities
│       └── fileUtils.js          # File operations
├── examples/
│   ├── sample_collection.json    # Example Postman collection
│   └── sample_env.json           # Example environment file
├── test/
│   └── example.js                # Usage examples
├── package.json                  # Dependencies & metadata
└── README.md                     # This file

Data Model

RunSummary

{
  collectionName: string,
  totalRequests: number,
  failedRequests: number,
  totalAssertions: number,
  failedAssertions: number,
  totalDuration: number,        // milliseconds
  startTime: string,            // ISO timestamp
  endTime: string,              // ISO timestamp
  passed: boolean,
  iterations: number,
  requests: RequestMetrics[]
}

RequestMetrics

{
  name: string,
  method: string,               // GET, POST, etc.
  url: string,
  statusCode: number,
  duration: number,             // milliseconds
  assertionsPassed: number,
  assertionsFailed: number,
  errors: string[],
  assertionDetails: {
    name: string,
    passed: boolean,
    error: string | null
  }[]
}

Development

Running Examples

# Show usage examples
node test/example.js

Testing with Sample Collection

# Run sample collection
collection-runner --collection ./examples/sample_collection.json --verbose

# Run with multiple iterations
collection-runner --collection ./examples/sample_collection.json --iterations 2 --report-dir ./test-reports

Code Quality

ES6+ JavaScript (CommonJS for CLI compatibility)
JSDoc type annotations
Consistent async/await patterns
Comprehensive error handling
Input validation for all arguments

Error Handling

CollectionRunner provides clear error messages for common issues:

❌ Missing required --collection argument
❌ Collection file not found
❌ Environment file not found
❌ Invalid iteration count
❌ Missing Telegram credentials
❌ Failed API requests
❌ Newman execution errors

Exit codes:

0 - Success (all tests passed)
1 - Failure (tests failed or error occurred)

Dependencies

newman - ^5.3.2 - Run Postman collections programmatically
axios - ^1.6.2 - HTTP client for Telegram API

No heavy dependencies! Report generation uses:

Chart.js via CDN (no local installation needed)
Pure HTML/CSS for styling
Vanilla JavaScript for interactivity

Browser Support

HTML reports work in all modern browsers:

Chrome/Edge 90+
Firefox 88+
Safari 14+

Performance

Handles collections with 100+ requests
Report generation < 1 second
Minimal memory footprint
Can run in CI/CD pipelines

Troubleshooting

Collection not found

# Ensure path is correct (absolute or relative to current directory)
collection-runner --collection /full/path/to/collection.json

Telegram notifications not working

# Verify credentials
# Check bot token: curl https://api.telegram.org/botYOUR_TOKEN/getMe
# Verify chat ID is correct (should be negative for groups)
collection-runner --collection ./my_collection.json --verbose

Report not generated

# Check report directory permissions
# Ensure report-dir exists or is writable
collection-runner --collection ./my_collection.json --report-dir ./reports --verbose

License

MIT

Contributing

Contributions welcome! Feel free to submit issues or pull requests.

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Made with ❤️ for API testers and QA engineers