Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/visible/cruel/llms.txt

Use this file to discover all available pages before exploring further.

What are Presets?

Presets are pre-configured chaos profiles optimized for different testing environments. They provide sensible defaults for development, staging, production, and stress testing scenarios.

Using Presets

Enable a preset globally to apply chaos to all wrapped functions:
import { cruel } from 'cruel'

// Wrap your functions
const fetchData = cruel(async () => { /* ... */ })
const processData = cruel(async () => { /* ... */ })

// Enable preset globally
cruel.enable(cruel.presets.development)

// Now all wrapped functions use the preset
await fetchData()
await processData()

Available Presets

development

Minimal chaos for local development:
cruel.enable(cruel.presets.development)
// { fail: 0.01, delay: [10, 100] }
  • Failure rate: 1% - Very rare failures
  • Delay: 10-100ms - Minimal latency
  • Use case: Daily development, fast feedback loops
Use development preset to catch obvious resilience issues without slowing down your workflow.

staging

Moderate chaos for pre-production testing:
cruel.enable(cruel.presets.staging)
// { fail: 0.05, delay: [50, 500], timeout: 0.02 }
  • Failure rate: 5% - Occasional failures
  • Delay: 50-500ms - Realistic latency
  • Timeout: 2% - Rare hangs
  • Use case: Integration testing, QA environments

production

Realistic production-like conditions:
cruel.enable(cruel.presets.production)
// { fail: 0.1, delay: [100, 1000], timeout: 0.05 }
  • Failure rate: 10% - Frequent failures
  • Delay: 100-1000ms - High latency
  • Timeout: 5% - Occasional hangs
  • Use case: Load testing, chaos engineering experiments
The production preset is for testing environments only. Never enable chaos in actual production without careful planning.

harsh

Aggressive chaos for stress testing:
cruel.enable(cruel.presets.harsh)
// { fail: 0.2, delay: [500, 2000], timeout: 0.1, jitter: 500 }
  • Failure rate: 20% - Very frequent failures
  • Delay: 500-2000ms - Significant latency
  • Timeout: 10% - Common hangs
  • Jitter: 0-500ms extra variance
  • Use case: Stress testing, finding edge cases

nightmare

Extreme chaos for worst-case testing:
cruel.enable(cruel.presets.nightmare)
// { fail: 0.4, delay: [1000, 5000], timeout: 0.2, jitter: 2000 }
  • Failure rate: 40% - Constant failures
  • Delay: 1-5 seconds - Severe latency
  • Timeout: 20% - Frequent hangs
  • Jitter: 0-2000ms extra variance
  • Use case: Testing recovery logic, maximum resilience

apocalypse

Complete system breakdown:
cruel.enable(cruel.presets.apocalypse)
// { fail: 0.6, delay: [2000, 10000], timeout: 0.3, jitter: 5000 }
  • Failure rate: 60% - Most calls fail
  • Delay: 2-10 seconds - Extreme latency
  • Timeout: 30% - Very frequent hangs
  • Jitter: 0-5000ms extra variance
  • Use case: Testing graceful degradation, system limits
apocalypse preset creates near-total failure. Only use when testing absolute worst-case scenarios.

Preset Comparison

PresetFail %Timeout %
development1%0%
staging5%2%
production10%5%
harsh20%10%
nightmare40%20%
apocalypse60%30%

Custom Presets

Create your own presets using cruel.profile():
import { cruel } from 'cruel'

// Define a custom preset
cruel.profile('mobile-network', {
  fail: 0.15,
  delay: [300, 1500],
  timeout: 0.08,
  jitter: 400
})

// Use your custom preset
cruel.useProfile('mobile-network')

// Or enable it directly
const mobileSettings = {
  fail: 0.15,
  delay: [300, 1500],
  timeout: 0.08,
  jitter: 400
}
cruel.enable(mobileSettings)

Per-Function Presets

Apply presets to individual functions:
import { cruel } from 'cruel'

// Different chaos levels for different functions
const critical = cruel(paymentService, cruel.presets.development)
const analytics = cruel(trackEvent, cruel.presets.nightmare)
const cache = cruel(getCachedData, cruel.presets.harsh)

Preset Recommendations

Development Workflow

// Local development
if (process.env.NODE_ENV === 'development') {
  cruel.enable(cruel.presets.development)
}

// CI/CD integration tests
if (process.env.CI) {
  cruel.enable(cruel.presets.staging)
}

// Load testing
if (process.env.LOAD_TEST) {
  cruel.enable(cruel.presets.production)
}

Progressive Testing

Gradually increase chaos intensity:
import { cruel } from 'cruel'

const testLevels = [
  { name: 'Basic', preset: cruel.presets.development },
  { name: 'Moderate', preset: cruel.presets.staging },
  { name: 'Realistic', preset: cruel.presets.production },
  { name: 'Stress', preset: cruel.presets.harsh },
  { name: 'Extreme', preset: cruel.presets.nightmare }
]

for (const level of testLevels) {
  console.log(`Testing with ${level.name} chaos...`)
  cruel.enable(level.preset)
  
  await runTestSuite()
  
  const stats = cruel.stats()
  console.log(`Success rate: ${((stats.calls - stats.failures) / stats.calls * 100).toFixed(1)}%`)
  
  cruel.disable()
  cruel.resetStats()
}

Combining with Other Features

With Scenarios

Use presets as base configuration for scenarios:
import { cruel } from 'cruel'

// Create scenario with preset as base
cruel.scenario('high-load', {
  chaos: {
    ...cruel.presets.production,
    spike: [2000, 5000]  // Add traffic spikes
  },
  duration: 60000
})

await cruel.play('high-load')

With Scopes

Apply presets to specific code sections:
import { cruel } from 'cruel'

// Critical section with minimal chaos
await cruel.scope(async () => {
  await processPayment()
  await sendConfirmation()
}, cruel.presets.development)

// Non-critical section with more chaos
await cruel.scope(async () => {
  await updateAnalytics()
  await refreshCache()
}, cruel.presets.harsh)

Environment-Specific Presets

import { cruel } from 'cruel'

function getChaosPreset() {
  const env = process.env.NODE_ENV
  
  switch (env) {
    case 'development':
      return cruel.presets.development
    case 'test':
      return cruel.presets.staging
    case 'staging':
      return cruel.presets.production
    case 'load-test':
      return cruel.presets.harsh
    default:
      return { enabled: false }
  }
}

cruel.enable(getChaosPreset())

Disabling Chaos

Turn off all chaos injection:
import { cruel } from 'cruel'

// Disable globally
cruel.disable()

// Check if enabled
if (cruel.isEnabled()) {
  console.log('Chaos is active')
}

// Toggle on/off
const isActive = cruel.toggle()
console.log('Chaos is now:', isActive ? 'enabled' : 'disabled')

Best Practices

Start small: Begin with development preset and gradually increase intensity as your resilience improves.
Test incrementally: Run tests with each preset level to identify your breaking points.
Document thresholds: Record which preset levels your system can handle and set that as your baseline.
Never in production: Presets are for testing environments only. Production chaos engineering requires careful planning and monitoring.

Next Steps

Scenarios

Simulate real-world failure scenarios over time

Chaos Injection

Learn about the underlying chaos injection mechanics

Statistics

Track and analyze chaos injection results

Configuration

Advanced configuration options

Build docs developers (and LLMs) love