OA Test Runner

A comprehensive command-line tool for managing, executing, and validating API tests against OpenAge services. The OA Test Runner enables developers to discover specs, run tests with validation, and manage authentication seamlessly.

Features

• Spec Discovery: Automatically discover and organize test specs from the $specs directory
• Test Execution: Run API tests with built-in request/response handling and validation
• Field Validation: Validate individual response fields against expected values
• Schema Validation: Validate entire response payloads against JSON schemas
• Template Injection: Use Handlebars templates to inject dynamic data into requests
• Data Encryption: Secure sensitive data with AES-256-CBC encryption
• Session Management: Handle login/logout and maintain authentication state

Project Structure

lib/
├── handlers/          # Command handlers
│   ├── test.js       # Test execution handler
│   ├── pull.js       # Pull configurations from remote
│   ├── push.js       # Push configurations to remote
│   ├── run.js        # Run command orchestration
│   ├── login.js      # Authentication
│   ├── logout.js     # Session cleanup
│   ├── script.js     # Script execution
│   ├── config.js     # Configuration management
│   ├── data.js       # Data operations
│   └── quit.js       # Application termination
├── helpers/
│   ├── http.js       # HTTP request execution
│   ├── request.js    # Request/response handling
│   ├── template.js   # Handlebars template processing
│   ├── file.js       # File operations
│   ├── data.js       # Data persistence and encryption
│   ├── crypto.js     # Encryption/decryption
│   ├── text.js       # Text formatting utilities
│   ├── input.js      # User input parsing
│   └── logger.js     # Logging
├── services/
│   ├── specs.js      # Test spec discovery and management
│   ├── oa.js         # OpenAge API endpoints
│   └── context.js    # Application context
├── validators/       # Validation handlers
│   ├── field.js      # Field-level validation
│   └── schema.js     # Schema validation
├── constants/
│   ├── actions.js    # Available commands
│   ├── inputs.js     # Input prompts and formats
│   ├── errors.js     # Error messages
│   └── transforms.js # Data transformations
└── index.js          # Main entry point

Installation

npm install

Usage

Test Spec Format

Test specs are JSON files with the following structure:

{
  "code": "test-user-session",
  "name": "Get User Session",
  "description": "Verify current user session details",
  "request": {
    "method": "GET",
    "url": "${directory}",
    "path": "api/sessions/current",
    "headers": {
      "Content-Type": "application/json"
    }
  },
  "validations": [
    {
      "field": "status",
      "operator": "eq",
      "value": 200
    },
    {
      "field": "data.user.email",
      "operator": "contains",
      "value": "@example.com"
    }
  ]
}

Template Injection

Use Handlebars templates to inject dynamic data:

{
  "request": {
    "url": "${service}",
    "path": "api/users/{{prompt.userId}}/profile"
  }
}

Available injectable objects:

• prompt.* - User input values
• response.* - Response data from previous tests
• context.* - Application context
• input.* - Input data storage

Data Encryption

Sensitive data is automatically encrypted using AES-256-CBC:

const { encrypt, decrypt } = require('./lib/helpers/crypto');

const encrypted = encrypt('sensitive-value');
const decrypted = decrypt(encrypted); // Returns: 'sensitive-value'

Machine secret is stored in $oa/secret.key with secure file permissions.

Validators

Field Validator

Validates individual response fields against operators:

• eq - Equals
• ne - Not equals
• gt - Greater than
• lt - Less than
• contains - String contains

Schema Validator

Validates entire response payload against JSON schemas.

Configuration

Settings are stored in $oa/settings/ directory with environment-specific files:

• default.json - Default configuration
• {env}.json - Environment-specific overrides (dev, qa, uat, stage, prod)

Data Storage

• $cache/specs/ - Cached spec metadata
• $cache/responses/ - Cached responses from tests
• $data/input/ - Stored input values
• $oa/secret.key - Machine encryption secret

Known Issues

• None currently documented

Release Notes

1.0.0

• Initial release
• Full test execution pipeline
• Field and schema validation
• Session management
• Data encryption

Contributing

Follow the existing code structure and include comprehensive JSDoc comments for new functions.

License

MIT - OpenAge