DEV Community

Cover image for Restflow: CLI tool for API testing
Monawwar Abdullah
Monawwar Abdullah

Posted on

Restflow: CLI tool for API testing

#cli #api #testing #webdev

What is Restflow?

Restflow is an innovative API testing and workflow automation tool that uses .flow files to define test scenarios in plain text. With Restflow, you can create comprehensive API test suites that are as easy to read as they are to write.

Key Features at a Glance

  • 🌊 Simple DSL: Write API tests in human-readable .flow files
  • 🔧 Variable Substitution: Dynamic values with {{variable}} syntax
  • 🌍 Environment Support: Multi-environment testing with .env files
  • ✅ Powerful Assertions: JSONPath and regex-based response validation
  • 📊 Multiple Output Formats: Console, JSON, and summary reports
  • 🔗 Step Dependencies: Capture values and chain requests
  • ⚡ Fast Execution: Concurrent processing with timeout support
  • 🎯 Built-in Variables: UUID, timestamp, random values out of the box

Why Restflow Stands Out

1. Human-Readable Syntax

Traditional API testing tools often require you to write complex JSON configurations or learn proprietary syntax. Restflow's DSL reads like documentation:

### Get User Profile
GET https://api.example.com/users/123
Authorization: Bearer {{token}}

> assert status == 200
> assert body.name == "John Doe"
> assert body.email contains "@example.com"
Enter fullscreen mode Exit fullscreen mode

Compare this to a typical JSON-based test configuration, and the difference is immediately clear – Restflow flows are self-documenting.

2. Zero Configuration Setup

Getting started with Restflow is as simple as:

# Create a new project with templates
pnpm create restflow

# Or add to an existing project
pnpm add -D @restflow/cli

# Or install globally
npm install -g @restflow/cli
Enter fullscreen mode Exit fullscreen mode

No complex configuration files, no framework setup – just create a .flow file and you're ready to test.

3. Built-in Intelligence

Restflow comes with intelligent built-in variables that generate fresh values on each run:

  • {{uuid}} - Generates unique UUIDs for test data
  • {{timestamp}} - Current Unix timestamp
  • {{randomString}} - Random alphanumeric strings
  • {{randomNumber}} - Random numbers for test scenarios

Real-World Use Cases

1. E-commerce Platform Testing

Let's say you're testing an e-commerce API. Here's how you might test the complete user journey:

### Register New Customer
POST https://api.shop.com/auth/register
Content-Type: application/json

{
  "email": "customer-{{uuid}}@test.com",
  "password": "SecurePass123",
  "firstName": "Test",
  "lastName": "Customer"
}

> assert status == 201
> assert body.success == true
> capture customerId = body.customer.id
> capture authToken = body.token

### Login Customer
POST https://api.shop.com/auth/login
Content-Type: application/json

{
  "email": "customer-{{uuid}}@test.com",
  "password": "SecurePass123"
}

> assert status == 200
> assert body.token != null
> capture loginToken = body.token

### Browse Products
GET https://api.shop.com/products?category=electronics
Authorization: Bearer {{loginToken}}

> assert status == 200
> assert body.products.length > 0
> capture firstProductId = body.products[0].id
> capture productPrice = body.products[0].price

### Add to Cart
POST https://api.shop.com/cart/add
Authorization: Bearer {{loginToken}}
Content-Type: application/json

{
  "productId": "{{firstProductId}}",
  "quantity": 2
}

> assert status == 200
> assert body.cart.items.length == 1
> assert body.cart.total == {{productPrice}} * 2

### Checkout Process
POST https://api.shop.com/orders/create
Authorization: Bearer {{loginToken}}
Content-Type: application/json

{
  "paymentMethod": "credit_card",
  "shippingAddress": {
    "street": "123 Test St",
    "city": "Test City",
    "zip": "12345"
  }
}

> assert status == 201
> assert body.order.status == "pending"
> assert body.order.customerId == "{{customerId}}"
> capture orderId = body.order.id
Enter fullscreen mode Exit fullscreen mode

2. Authentication & Authorization Testing

Testing complex auth flows becomes straightforward:

### Admin Login
POST https://api.company.com/auth/admin/login
Content-Type: application/json

{
  "username": "{{adminUser}}",
  "password": "{{adminPassword}}"
}

> assert status == 200
> assert body.user.role == "admin"
> assert body.permissions contains "user_management"
> capture adminToken = body.token

### Create Regular User
POST https://api.company.com/users
Authorization: Bearer {{adminToken}}
Content-Type: application/json

{
  "username": "testuser_{{timestamp}}",
  "email": "user{{randomNumber}}@test.com",
  "role": "user"
}

> assert status == 201
> capture newUserId = body.id

### Test Permission Boundaries
DELETE https://api.company.com/users/{{newUserId}}
Authorization: Bearer {{userToken}}

> assert status == 403
> assert body.error == "Insufficient permissions"

### Admin Can Delete User
DELETE https://api.company.com/users/{{newUserId}}
Authorization: Bearer {{adminToken}}

> assert status == 204
Enter fullscreen mode Exit fullscreen mode

Advanced Features

Environment-Specific Testing

Restflow makes multi-environment testing seamless:

# Development environment
restflow run flows/ --env .env.dev

# Staging environment  
restflow run flows/ --env .env.staging

# Production health checks
restflow run health-checks/ --env .env.prod
Enter fullscreen mode Exit fullscreen mode

Your .env.staging file might look like:

BASE_URL=https://staging-api.example.com
API_KEY=staging_key_12345
DATABASE_URL=postgres://staging-db:5432/app
TIMEOUT=30000
Enter fullscreen mode Exit fullscreen mode

Multiple Output Formats

Restflow adapts to different needs:

# Human-readable console output (default)
restflow run flows/

# JSON for CI/CD integration
restflow run flows/ --format json > test-results.json

# Concise summary for monitoring
restflow run flows/ --format summary
Enter fullscreen mode Exit fullscreen mode

Variable Hierarchy and Overrides

Restflow provides a sophisticated variable system with clear precedence:

  1. Built-in variables (lowest priority): {{uuid}}, {{timestamp}}
  2. Environment variables: From .env files
  3. Captured variables: From previous response steps
  4. CLI variables (highest priority): Passed via command line

This means you can override built-in variables when needed:

# Override for consistent testing
uuid=test-user-12345
timestamp=1640995200
Enter fullscreen mode Exit fullscreen mode

Integration with CI/CD

Restflow is designed for seamless integration into modern development workflows:

GitHub Actions 

name: API Tests
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Restflow
        run: npm install -g @restflow/cli

      - name: Run API Tests
        run: restflow run tests/api/ --env .env.ci --format json

      - name: Upload Results
        uses: actions/upload-artifact@v3
        with:
          name: api-test-results
          path: test-results.json
Enter fullscreen mode Exit fullscreen mode

Docker Integration 

FROM node:18-alpine
RUN npm install -g @restflow/cli
COPY flows/ /app/flows/
COPY .env.docker /app/.env
WORKDIR /app
CMD ["restflow", "run", "flows/", "--env", ".env", "--format", "json"]
Enter fullscreen mode Exit fullscreen mode

Performance and Scalability

Restflow is built for performance:

  • Concurrent Execution: Multiple requests run in parallel
  • Configurable Timeouts: Fine-tune performance for your needs
  • Efficient Memory Usage: Minimal overhead for large test suites
  • Fast Startup: No heavy framework initialization 
# Run with custom timeout and verbose output
restflow run large-test-suite/ --timeout 60000 --verbose
Enter fullscreen mode Exit fullscreen mode

Best Practices and Patterns

1. Modular Flow Design

Organize flows by feature or service:

flows/
├── auth/
│   ├── 01-registration.flow
│   ├── 02-login.flow
│   └── 03-password-reset.flow
├── users/
│   ├── 01-profile-crud.flow
│   ├── 02-permissions.flow
│   └── 03-user-search.flow
└── orders/
    ├── 01-create-order.flow
    ├── 02-order-status.flow
    └── 03-order-cancellation.flow
Enter fullscreen mode Exit fullscreen mode

2. Effective Variable Usage

Use descriptive variable names and leverage the hierarchy:

### Setup Test Data
POST {{BASE_URL}}/test-data/setup
Content-Type: application/json

{
  "scenario": "user_registration_flow",
  "timestamp": "{{timestamp}}"
}

> capture testDataId = body.id

### Use Test Data
GET {{BASE_URL}}/data/{{testDataId}}
X-Test-Run: {{uuid}}

> assert body.scenario == "user_registration_flow"
Enter fullscreen mode Exit fullscreen mode

3. Comprehensive Error Testing

Don't just test the happy path:

### Test Rate Limiting
POST {{BASE_URL}}/api/endpoint
Content-Type: application/json

{"data": "test"}

> assert status == 200

### Trigger Rate Limit
POST {{BASE_URL}}/api/endpoint
POST {{BASE_URL}}/api/endpoint
POST {{BASE_URL}}/api/endpoint
POST {{BASE_URL}}/api/endpoint
POST {{BASE_URL}}/api/endpoint

> assert status == 429
> assert body.error contains "rate limit"
> assert headers["retry-after"] matches "\\d+"
Enter fullscreen mode Exit fullscreen mode

The Future of API Testing

Restflow represents a paradigm shift in API testing philosophy. By prioritizing readability, simplicity, and developer experience, it enables teams to:

  • Write tests faster: No complex setup or learning curve
  • Maintain tests easier: Human-readable syntax that doubles as documentation
  • Collaborate better: Non-technical team members can understand and contribute
  • Scale confidently: Robust execution engine handles complex scenarios

Upcoming Features

The Restflow roadmap includes exciting developments:

  • GUI Test Builder: Visual flow creation for non-technical users
  • Real-time Monitoring: Continuous API health monitoring
  • Advanced Reporting: Detailed analytics and trend analysis
  • Plugin System: Extensible architecture for custom functionality
  • Cloud Integration: Hosted execution and collaboration features

Resources

  • GitHub Repository: https://github.com/mxvsh/restflow
  • Documentation: Comprehensive guides in the repository
  • Examples: Real-world flows in the examples/ directory
  • Community: Join discussions in GitHub Issues
  • NPM Package: @restflow/cli for global installation

Transform your API testing workflow with Restflow – where simplicity meets power, and testing becomes a joy rather than a chore.

Top comments (0)