xk6-edi

A comprehensive k6 extension for generating synthetic HIPAA X12 EDI transactions for load testing healthcare systems.

Features

• Complete Transaction Coverage: Support for all 7 core HIPAA X12 transaction types:
  • 837P - Professional Claims
  • 837D - Dental Claims
  • 835 - Healthcare Payment/Advice
  • 270 - Eligibility Inquiry
  • 271 - Eligibility Response
  • 276 - Claim Status Inquiry
  • 277 - Claim Status Response
• Deterministic Generation: Reproducible synthetic data using configurable seeds
• HIPAA 5010 Compliance: Follows official implementation guides for transaction structure
• High Performance: Optimized for high-throughput load testing (3,000+ TPS)
• Comprehensive Validation: Multi-level validation engine with detailed error reporting
• Parallel Processing: Concurrent batch generation with configurable concurrency
• Modular Architecture: Extensible provider system with clean separation of concerns

Installation

Prerequisites

• Go 1.21+
• xk6 build tool

Build the Extension

# Install xk6
go install go.k6.io/xk6/cmd/xk6@latest

# Build k6 with the EDI extension
xk6 build --with github.com/sigma/xk6-edi=.

This creates a k6 binary in your current directory with the EDI extension included.

Usage

Basic Example

// examples/basic_generation.js
import edi from 'k6/x/edi';

export default function () {
    const result = edi.generate({
        transactionType: '837P',
        seed: 12345,
        config: {
            claimCount: 1,
            validationLevel: 'moderate',
            includeSecondary: false
        }
    });

    console.log(`Generated ${result.transactionType} transaction`);
    console.log(`Data length: ${result.data.length} characters`);
}

Batch Generation

// examples/batch_generation.js
import edi from 'k6/x/edi';

export default function () {
    const batchResult = edi.generateBatch({
        requests: [
            { transactionType: '837P', seed: 12345, config: { claimCount: 1 } },
            { transactionType: '837P', seed: 12346, config: { claimCount: 2 } }
        ],
        parallel: false
    });

    console.log(`Generated ${batchResult.totalCount} transactions`);
}

Validation

// examples/validation.js
import edi from 'k6/x/edi';

export default function () {
    const result = edi.generate({
        transactionType: '837P',
        seed: 12345,
        config: { claimCount: 1 }
    });
    
    const validationResult = edi.validate('837P', result.data);
    console.log(`Validation errors: ${validationResult.validationErrors.length}`);
}

Load Testing

// examples/load_test.js
import edi from 'k6/x/edi';

export let options = {
    stages: [
        { duration: '30s', target: 10 },
        { duration: '1m', target: 50 },
        { duration: '30s', target: 0 },
    ],
};

export default function () {
    const seed = __VU * 1000 + __ITER;
    const result = edi.generate({
        transactionType: '837P',
        seed: seed,
        config: { claimCount: Math.floor(Math.random() * 3) + 1 }
    });
    
    if (!result.data || result.data.length < 100) {
        throw new Error('Generated transaction is too short');
    }
}

API Reference

edi.generate(params)

Generates a single EDI transaction.

Parameters:

• transactionType (string): Transaction type (e.g., "837P")
• seed (number): Deterministic seed for reproducible data
• config (object): Provider-specific configuration

Returns: GenerateResponse object with transaction data and metadata.

edi.generateBatch(params)

Generates multiple EDI transactions.

Parameters:

• requests (array): Array of generation requests
• parallel (boolean): Whether to generate in parallel (not yet implemented)

Returns: BatchGenerateResponse object with results and statistics.

edi.validate(transactionType, data)

Validates an existing EDI transaction.

Parameters:

• transactionType (string): Transaction type
• data (string): X12 EDI data to validate

Returns: GenerateResponse object with validation results.

edi.getProviders()

Lists all available transaction providers.

Returns: Object mapping transaction types to provider metadata.

Configuration

837P Provider Configuration

{
    claimCount: 1,              // Number of claims per transaction
    validationLevel: 'moderate', // 'strict', 'moderate', or 'lenient'
    includeSecondary: false,    // Include secondary insurance
    submitterID: '',            // Custom submitter ID
    receiverID: '',             // Custom receiver ID
    testIndicator: true         // Use test indicator
}

Architecture

The extension follows a modular architecture with these core subsystems:

• API Layer: JavaScript bindings and k6 integration
• Provider Registry: Pluggable transaction generators
• Validation Engine: HIPAA 5010 compliance validation
• Template Engine: X12 segment generation
• Data Generation: Realistic synthetic healthcare data
• Code Store Management: Healthcare code sets (ICD-10, HCPCS, NPI)

Development

Project Structure

xk6-edi/
├── api/           # JavaScript API bindings
├── providers/     # Transaction providers (837P, 835, etc.)
├── validation/    # Validation engine and rules
├── templates/     # X12 segment templates
├── generators/    # Test data generators
├── codes/         # Healthcare code store management
├── types/         # Shared type definitions
└── docs/          # Documentation

Running Tests

# Run unit tests
go test ./...

# Run the test script
./k6 run working_test.js

Adding New Transaction Types

1. Create a new provider in providers/provider_XXX.go
2. Implement the Provider interface
3. Add validation rules in validation/
4. Register the provider in providers/registry.go
5. Add tests and documentation

Compliance

This extension generates synthetic test data only and should never be used with real PHI (Protected Health Information). All generated data is fictional and complies with HIPAA privacy requirements for testing environments.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

For issues, questions, or contributions, please visit the GitHub repository.