ZAP Runner

A cross-platform runner for executing ZAP API collections that works in both CLI and VS Code environments.

Features

✅ Cross-Platform Compatibility

• CLI Usage: Run from command line in Node.js environments
• VS Code Integration: Execute directly from VS Code workbench
• Browser Compatible: Uses web-compatible APIs for VS Code extension

✅ Execution Modes

• Single Request: Execute individual .zap request files
• Collection: Execute entire API collections
• Folder: Execute specific folders within collections
• Parallel/Sequential: Configurable execution modes

✅ Testing & Validation

• Test Execution: Runs JavaScript test code in requests
• Assertion Validation: Validates response assertions
• Error Handling: Comprehensive error reporting and timeout handling
• Logging: Detailed execution logs saved to logs/ folder

Architecture

Adapter Pattern

The runner uses an adapter pattern to work across environments:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   ZAP Runner    │───▶│   Adapter Set    │───▶│  Environment    │
│                 │    │                  │    │                 │
│ - executeRequest│    │ - FileSystem     │    │ - Node.js CLI   │
│ - executeCollection  │ - HTTP           │    │ - VS Code Web   │
│ - executeFolder │    │ - Logger         │    │                 │
└─────────────────┘    │ - Environment    │    └─────────────────┘
                       └──────────────────┘

Adapters

• FileSystemAdapter: File operations (Node.js fs vs VS Code IFileService)
• HttpAdapter: HTTP requests (Node.js axios vs Web fetch)
• LoggerAdapter: Logging (Node.js console vs VS Code IOutputService)
• EnvironmentAdapter: Environment detection and variables

Usage

CLI Usage

# Install dependencies
npm install

# Build the runner
npm run build

# Execute a single request
zap-runner request ./my-request.zap --variables ./env.json

# Execute entire collection
zap-runner collection ./my-collection --parallel --continue-on-error

# Execute specific folder
zap-runner folder ./my-collection "api/users" --verbose

# Validate collection structure
zap-runner validate ./my-collection

VS Code Usage

The runner integrates with VS Code through commands:

1. Run Current ZAP Request - Execute the currently open .zap file
2. Run ZAP Collection - Execute all requests in workspace
3. Run ZAP Folder - Execute specific folder within collection
4. Validate ZAP Collection - Validate collection structure

Access via:

• Command Palette (Ctrl+Shift+P)
• Editor toolbar (play button on .zap files)
• Explorer context menu

Programmatic Usage

import { ZapRunner, AdapterFactory } from 'zap-runner';

// For Node.js
const runner = new ZapRunner({
  timeout: 5000,
  parallel: true,
  continueOnError: true
}, AdapterFactory.createNodeAdapters());

// For VS Code
const runner = new ZapRunner({
  outputDir: 'logs',
  verbose: true
}, AdapterFactory.createVSCodeAdapters(vscodeServices));

// Execute collection
const result = await runner.executeCollection(fileMap, variables);

Configuration

interface RunnerConfig {
  timeout: number;           // Request timeout (ms)
  retries: number;          // Retry attempts
  delay: number;            // Delay between requests (ms)
  environment: Record<string, any>;  // Environment variables
  outputDir: string;        // Output directory for logs
  verbose: boolean;         // Verbose logging
  continueOnError: boolean; // Continue on request failure
  parallel: boolean;        // Execute requests in parallel
  maxConcurrent: number;    // Max concurrent requests
}

Output Structure

logs/
├── collection-name-2025-07-10T10-30-45-results.json
├── collection-name-2025-07-10T10-30-45-logs.json
├── collection-name-2025-07-10T10-30-45-summary.txt
└── request-name-2025-07-10T10-30-45-logs.json

Results JSON

{
  "collection": { /* Collection metadata */ },
  "requests": [
    {
      "request": { /* Request details */ },
      "status": "success|error|timeout",
      "response": { /* HTTP response */ },
      "tests": [ /* Test results */ ],
      "assertions": [ /* Assertion results */ ],
      "duration": 1250,
      "timestamp": "2025-07-10T10:30:45.123Z"
    }
  ],
  "summary": {
    "total": 10,
    "passed": 8,
    "failed": 2,
    "duration": 15000
  }
}

Integration with ZAP Lang

The runner depends on the zap-lang package for:

• Parsing: .zap file parsing and validation
• Discovery: Collection and folder discovery
• Variables: Variable resolution and merging
• Conversion: Converting ZAP requests to HTTP configs

Development

# Install dependencies
npm install

# Development mode (watch)
npm run dev

# Run tests
npm test

# Build for production
npm run build

VS Code Integration Points

1. Service Registration: ZapRunnerService registered with VS Code DI
2. Commands: Actions registered for execution commands
3. Context Menus: Integration with file explorer and editor
4. Output Channel: Logs displayed in dedicated output channel
5. Notifications: Success/error notifications for user feedback

This runner provides a complete execution environment for ZAP collections while maintaining compatibility across CLI and VS Code environments.