pingpong-cli

v1.1.1

Published

8 days ago

Fast & Beautiful CLI API Testing Tool

0High
0Medium
0Low

0xdps

api testing cli http rest curl httpie api-client api-testing http-client

🏓 PingPong CLI

Fast, beautiful, and powerful command-line API testing tool.

✨ Features

🚀 Blazing fast - Built with pingpong-fetch v1.2.0 and Undici (2-3x faster than native fetch), ~42KB gzipped
🔗 Query parameters - Built-in support for clean query param handling
📋 Case-insensitive headers - RFC 2616 compliant header access
🎨 Beautiful output - Colorful responses with syntax highlighting
📝 Interactive mode - Build requests with guided prompts
📁 Collections - Organize and reuse requests
🌍 Environments - Switch between dev/staging/prod with variables
🔗 Request chaining - Extract values from responses, use in next requests
🍪 Cookie management - Automatic cookie handling with persistent storage
✅ Assertions - Validate responses for CI/CD pipelines
⚡ Load testing - Performance testing with concurrent requests and detailed metrics
📤 File uploads - Multipart form data support
🔒 Proxy support - Route requests through HTTP proxies

📦 Installation

# Install globally
npm install -g pingpong-cli

# Or use with npx (no install needed)
npx pingpong-cli send GET https://api.mockly.codes/users

⚡ Performance

Bundle Size: ~42KB gzipped (optimized with minification)
Build Time: Fast compilation with TypeScript
Runtime Speed: Built on Undici for maximum performance
Memory Usage: Efficient multipart/form-data handling

🚀 Quick Start

# Simple GET request
pingpong send GET https://api.mockly.codes/users

# POST with JSON
pingpong send POST https://api.mockly.codes/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"[email protected]"}'

# Interactive mode
pingpong request

# Load testing
pingpong load https://api.mockly.codes/health -n 100 -c 10

📖 Examples

Check out the examples directory for complete working examples of all features:

Basic Requests - GET, POST, Headers
Request Chaining - Extract and reuse values
Collections - Organize and manage requests
Assertions - Validate responses
File Operations - Upload files and send from files
Load Testing - Performance testing
Advanced Features - Proxies, cookies, interactive mode
CI/CD Integration - GitHub Actions workflow

See examples/README.md for complete example documentation.

📚 Commands

`send` - Send HTTP Request

pingpong send <METHOD> <URL> [options]

Options:
  -H, --header <key:value>   Headers (repeatable)
  -d, --data <body>          Request body (JSON or @file)
  -f, --file <name=@path>    Upload files
  -t, --timeout <ms>         Request timeout
  -x, --proxy <url>          HTTP proxy
  -a, --assert <assertion>   Response assertions
  -e, --extract <var=path>   Extract variables
  --no-redirect              Don't follow redirects
  --no-cookies               Disable cookies
  --no-save                  Don't save to history
  --show-headers             Display response headers (hidden by default)

Examples:
  pingpong send GET https://httpbin.org/get
  pingpong send POST https://api.mockly.codes/users -d @body.json
  pingpong send POST https://api.mockly.codes/upload -f "[email protected]"
  pingpong send GET https://api.mockly.codes/users --show-headers

`collection` - Manage Collections

# Create collection
pingpong collection:create my-api --base-url https://api.mockly.codes

# Add requests with chaining
pingpong collection:add my-api login \
  -m POST -u /auth/login \
  -d '{"email":"[email protected]","password":"pass"}' \
  -e "token=$.token" \
  -a "status == 200"

pingpong collection:add my-api get-profile \
  -m GET -u /users/me \
  -H "Authorization: Bearer {{token}}" \
  -e "userId=$.id"

# Run collection
pingpong collection:run my-api -e dev

# Run from JSON file
pingpong collection:run collection.json --file

# Show response headers
pingpong collection:run my-api --show-headers

`env` - Manage Environments

# Create environment
pingpong env:create dev
pingpong env:set dev BASE_URL https://pingpong.codes/
pingpong env:set dev API_KEY dev_key_123

# Use in requests
pingpong env:use dev
pingpong send GET "{{BASE_URL}}/users" -H "X-API-Key: {{API_KEY}}"

`load` - Load Testing

# Simple load test
pingpong load https://api.mockly.codes/users -n 100 -c 10

# Duration-based test
pingpong load https://api.mockly.codes/health \
  --duration 60 \
  --rate 20 \
  -c 20

# Collection load test
pingpong collection:run my-api --load -n 50 -c 5

Metrics Provided:

Latency: min, mean, median, p95, p99, max
Throughput: requests/sec, bytes/sec
Status code distribution
Virtual user statistics

🔗 Request Chaining

Extract values from responses and use them in subsequent requests:

# Extract token from login
pingpong send POST https://api.mockly.codes/auth/login \
  -d '{"email":"[email protected]","password":"pass"}' \
  --extract "token=$.token"

# Use token in next request
pingpong send GET https://api.mockly.codes/users/me \
  -H "Authorization: Bearer {{token}}"

JSONPath Syntax:

$.property - Root property
$.nested.value - Nested property
$.array[0] - Array element
$.items[*] - All array items

✅ Assertions

Validate responses for CI/CD:

# Status and timing
pingpong send GET https://api.mockly.codes/health \
  -a "status == 200" \
  -a "time < 1000"

# Headers
pingpong send GET https://api.mockly.codes \
  -a "header.content-type == 'application/json'"

# JSON body
pingpong send GET https://api.mockly.codes/users/1 \
  -a "body.id == 1" \
  -a "body.email exists"

🍪 Cookie Management

# List cookies
pingpong cookies

# Clear cookies
pingpong cookies:clear [domain]

# Export/Import
pingpong cookies:export cookies.json
pingpong cookies:import cookies.json

🎯 Complete Example

# 1. Create collection
pingpong collection:create my-api --base-url https://api.mockly.codes

# 2. Add login (extracts token)
pingpong collection:add my-api login \
  -m POST -u /auth/login \
  -d '{"email":"[email protected]","password":"pass"}' \
  -e "token=$.token" \
  -a "status == 200"

# 3. Add profile request (uses token)
pingpong collection:add my-api get-profile \
  -m GET -u /users/me \
  -H "Authorization: Bearer {{token}}" \
  -e "userId=$.id"

# 4. Run entire flow
pingpong collection:run my-api -e dev

# 5. Load test the flow
pingpong collection:run my-api --load -n 50 -c 5

# 6. Export and share
pingpong collection:export my-api my-api.json

🔄 CI/CD Integration

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

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install PingPong CLI
        run: npm install -g pingpong-cli
      
      - name: Run API tests
        run: |
          pingpong send GET ${{ secrets.API_URL }}/health \
            --assert "status == 200" \
            --assert "time < 2000" \
            --no-save

🆚 Why PingPong CLI?

| Feature | PingPong | curl | httpie | Postman CLI | |---------|-----------|------|--------|-------------| | Speed | ⚡⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡ | | Beautiful output | ✅ | ❌ | ✅ | ✅ | | Interactive mode | ✅ | ❌ | ❌ | ❌ | | Collections | ✅ | ❌ | ❌ | ✅ | | Load testing | ✅ | ❌ | ❌ | ⚠️ | | Request chaining | ✅ | ❌ | ❌ | ✅ | | Assertions | ✅ | ❌ | ❌ | ✅ | | Free & Open Source | ✅ | ✅ | ✅ | ⚠️ Limited |

💡 Tips & Tricks

# Load body from file
pingpong send POST https://api.mockly.codes/data -d @body.json

# Multiple headers
pingpong send GET https://api.mockly.codes \
  -H "Accept: application/json" \
  -H "User-Agent: MyApp/1.0"

# Custom timeout
pingpong send GET https://slow-api.example.com --timeout 60000

# Don't save sensitive requests
pingpong send POST https://api.mockly.codes/auth --no-save

# Use proxy for debugging
pingpong send GET https://api.mockly.codes -x http://localhost:8888

🔧 Configuration

# View config
pingpong config

# Set timeout
pingpong config --set defaultTimeout=5000

# Set max history
pingpong config --set maxHistoryItems=200

Storage Location: All data is stored in ~/.config/pingpong/:

collections.json - Request collections
environments.json - Environment variables
history.json - Request history
cookies.json - Cookie storage
config.json - CLI configuration

📖 More Resources

Full Documentation - Complete CLI guide
Browser Extension - API testing in your browser
pingpong-fetch v1.2.0 - Universal HTTP client (query params, case-insensitive headers)
pingpong-core v1.1.0 - Core utilities (HTTP types, URL/header utilities)
Changelog - Version history
Contributing - Development guide

🐛 Issues & Support

Bug reports: GitHub Issues
Questions: GitHub Discussions
Email: [email protected]

📄 License

MIT License - see LICENSE

🙏 Credits

Built with:

undici - Fast HTTP client
commander - CLI framework
chalk - Terminal colors
inquirer - Interactive prompts
ora - Elegant spinners

Made with ❤️ by 0xdps

🏓 PingPong CLI - Fast, beautiful API testing 🚀