Skip to content

README.md

Latest commit

 

History

History
237 lines (201 loc) · 6.99 KB

README.md

File metadata and controls

237 lines (201 loc) · 6.99 KB
Raw

Luminara Testing Environment

This testing environment programmatically validates all Luminara features as they would be used in real JavaScript applications across all frameworks.

🌐 Framework-Agnostic Testing: While some tests simulate React-like patterns, Luminara works identically across React, Vue, Angular, Svelte, vanilla JavaScript, and any modern browser environment.

🧪 Test Structure

test-cli/
├── package.json           # Test environment dependencies
├── testRunner.js          # Main test runner
├── testUtils.js           # Shared testing utilities
├── tests/
│   ├── basic.test.js      # Basic HTTP operations
│   ├── retry.test.js      # Retry system validation
│   ├── backoff.test.js    # All backoff strategies
│   ├── rateLimit.test.js  # Rate limiting with token bucket algorithm
│   ├── debouncer.test.js  # Request debouncing validation
│   ├── deduplicator.test.js  # Request deduplication tests
│   ├── interceptors.test.js    # Interceptor system tests
│   ├── timeout.test.js    # Timeout and abort scenarios
│   ├── drivers.test.js    # Custom driver tests
│   ├── stats.test.js      # Statistics system validation
│   ├── errors.test.js     # Error handling tests
│   ├── responseTypes.test.js   # Response type handling
│   ├── parseResponse.test.js   # Response parsing validation
│   └── reactSimulation.test.js  # Framework usage patterns
└── README.md              # This file

🚀 Quick Start

# Install test dependencies
cd test-cli
npm install

# Run all tests
npm test

# Run specific test suites
npm run test:basic
npm run test:retry
npm run test:backoff
npm run test:rate-limit
npm run test:debouncer
npm run test:deduplicator
npm run test:interceptors
npm run test:timeout
npm run test:drivers
npm run test:stats
npm run test:errors
npm run test:response-types
npm run test:parse-response
npm run test:react-simulation

# Watch mode for development
npm run test:watch

✅ Test Coverage

Basic HTTP Operations

  • GET/POST/PUT/PATCH/DELETE methods
  • JSON/Text/Form data handling
  • Base URL configuration
  • Query parameters
  • Custom headers

Retry & Backoff Strategies

  • Linear backoff timing validation
  • Exponential backoff growth patterns
  • Fibonacci sequence verification
  • Jitter randomization bounds
  • Exponential jitter combinations
  • Custom retry handlers
  • Status code filtering

Request Hedging

  • Race policy (concurrent requests)
  • Cancel-and-retry policy (sequential with cancellation)
  • HTTP method whitelist validation (GET/HEAD/OPTIONS)
  • Exponential backoff timing for hedges
  • Jitter randomization for hedge delays
  • Per-request override (bidirectional)
  • Server rotation support
  • Integration with retry and timeout
  • Stats tracking for hedging metrics
  • Edge cases (errors, short delays, maxHedges limits)

Rate Limiting

  • Token bucket algorithm validation
  • Burst capacity enforcement
  • Request scheduling behavior
  • Global/domain/endpoint scoping
  • Pattern-based include/exclude rules
  • Statistics tracking accuracy
  • Dynamic configuration updates

Debouncer

  • Search-as-you-type patterns (300ms delay)
  • Button click spam protection
  • Method-specific debouncing (GET only)
  • Custom key generation strategies
  • Request cancellation behavior
  • Delay configuration validation
  • Stats integration accuracy
  • Debouncer + retry interaction

Request Deduplicator

  • Disabled by default verification
  • Basic deduplication (3→1 request)
  • Key strategy validation (url vs url+method)
  • Method filtering (excludeMethods/methods)
  • Cache TTL burst protection (100ms default)
  • Cache TTL = 0 (in-flight only mode)
  • Per-request disable override
  • Custom key generator functions
  • Error propagation to duplicates
  • AbortController integration
  • Sequential request behavior
  • Integration with retry logic
  • maxCacheSize enforcement
  • Concurrent identical requests

Interceptors

  • Request interceptors
  • Response transformers
  • Error handlers
  • Interceptor chaining
  • Context passing
  • Deterministic execution order
  • Mutable context sharing

Stats System

  • Real-time metrics collection
  • Query interface with grouping
  • Performance analytics
  • Rate calculations
  • Error categorization
  • Reset functionality
  • Snapshot capabilities

Error Handling

  • Network error scenarios
  • HTTP status code errors
  • Timeout error handling
  • Abort error scenarios
  • Error recovery patterns
  • Custom error processing

Response Type Handling

  • JSON response processing
  • Text response handling
  • Form data responses
  • Binary data handling
  • Content-Type detection
  • Response parsing validation

Timeout & Abort

  • Timeout enforcement
  • AbortController integration
  • Request cancellation
  • Cleanup behavior

Custom Drivers

  • Driver interface compliance
  • Request/response mapping
  • Error handling
  • Signal propagation

Framework Simulation

  • useEffect patterns (React-like)
  • State management patterns
  • Error boundaries simulation
  • Component lifecycle patterns
  • Concurrent requests handling

🎯 Features

  • Programmatic Testing: Validates actual behavior, not just API contracts
  • Framework Simulation: Tests common patterns used across JavaScript frameworks
  • Mock Server: Controlled HTTP responses for predictable testing
  • Timing Validation: Ensures backoff strategies work as expected
  • Error Scenarios: Tests failure cases and recovery
  • Performance Monitoring: Measures request timing and resource usage
  • Real Package Import: Tests the actual built package, not source files

📊 Test Output

Tests provide detailed output including:

  • ✅ Pass/fail status with descriptive messages
  • ⏱️ Timing measurements for backoff validation
  • 📈 Performance metrics
  • 🐛 Error details with stack traces
  • 📋 Summary statistics

🔧 Configuration

Tests can be configured via environment variables:

  • TEST_TIMEOUT=10000 - Global test timeout (default: 10s)
  • MOCK_SERVER_PORT=4201 - Mock server port (default: 4201)
  • VERBOSE=true - Enable verbose logging
  • SKIP_SLOW=true - Skip long-running tests

🎭 Mock Server

The included mock server provides:

  • Configurable delays for timeout testing
  • Status code control for retry testing
  • Request counting for backoff validation
  • CORS headers for browser compatibility
  • JSON/Text/Form response types

🔄 Continuous Testing

Ideal for:

  • Pre-commit hooks
  • CI/CD pipelines
  • Development workflow
  • Release validation
  • Performance regression detection

🧩 Integration

Tests import directly from source (../../src/index.js), ensuring:

  • Fast development iteration (no build step)
  • Testing actual source code
  • No package recursion issues
  • Immediate feedback on changes

Note: Tests use source imports, not the built package. This means:

  • ✅ No luminara dependency needed in package.json
  • ✅ Changes to src/ are immediately testable
  • ✅ No risk of recursive folder structure (20GB+ issue)
  • ⚠️ Tests validate source behavior, not the built bundle