Configuration File Guide

FakeDataDSL supports YAML configuration files following Rails conventions. This allows you to configure the gem without code changes and have environment-specific settings.

Quick Start

Create config/fake_data_dsl.yml:

default_mode: random
max_unique_retries: 1000

limits:
  max_array_size: 100
  max_recursion: 5

The configuration is automatically loaded when FakeDataDSL initializes.

File Locations

FakeDataDSL searches for configuration files in this order:

  1. config/fake_data_dsl.yml (Rails convention)
  2. fake_data_dsl.yml (project root)
  3. .fake_data_dsl.yml (hidden file)

The first file found is used.

Configuration Options

Core Settings

# Default generation mode
# Options: random, edge, invalid, hostile, mixed
default_mode: random

# Maximum retries for unique value generation
max_unique_retries: 1000

# Allow eval() in custom expressions (security risk!)
allow_eval: false

# Use FastEngine for batch generation (not thread-safe)
fast_mode: false

Field Handling

# Probability that optional fields appear (0.0 - 1.0)
optional_field_presence_rate: 0.8

# Probability that nullable fields are null (0.0 - 1.0)
nullable_field_null_rate: 0.1

Resource Limits

limits:
  # Maximum artificial latency in milliseconds
  max_latency_ms: 10000

  # Maximum recursion depth for nested schemas
  max_recursion: 10

  # Maximum array size
  max_array_size: 1000

  # Maximum text length
  max_text_length: 10000

Environment-Specific Configuration

Override settings per environment:

# Base configuration (applies to all environments)
default_mode: random
max_unique_retries: 1000

limits:
  max_array_size: 100

# Test environment overrides
test:
  default_mode: edge        # Use edge cases in tests
  max_unique_retries: 100   # Faster test failures
  limits:
    max_array_size: 10      # Smaller arrays in tests

# Development environment
development:
  default_mode: random

# Production environment
production:
  fast_mode: true
  limits:
    max_array_size: 1000

Environment Detection

FakeDataDSL detects the environment from these variables (in order):

  1. RAILS_ENV
  2. RACK_ENV
  3. FAKE_DATA_DSL_ENV
  4. Default: "development"

Manual Configuration

Load from Custom Path

# Load specific file
FakeDataDSL::ConfigFile.load_and_apply("custom/path/config.yml")

# Load with specific environment
FakeDataDSL::ConfigFile.load_and_apply("config.yml", env: "staging")

Load Without Applying

# Just load the config hash
config = FakeDataDSL::ConfigFile.load("config.yml", env: "test")
puts config["default_mode"]  # => "edge"

# Apply later
FakeDataDSL::ConfigFile.apply(config)

Check Config File Location

path = FakeDataDSL::ConfigFile.find_config_file
puts "Using config: #{path || 'none found'}"

Complete Example

# config/fake_data_dsl.yml

# =========================================
# Base Configuration (all environments)
# =========================================

# Generation settings
default_mode: random
max_unique_retries: 1000

# Field behavior
optional_field_presence_rate: 0.8
nullable_field_null_rate: 0.1

# Resource limits
limits:
  max_latency_ms: 10000
  max_recursion: 10
  max_array_size: 100
  max_text_length: 10000

# =========================================
# Test Environment
# =========================================
test:
  # Deterministic for reproducible tests
  default_mode: random

  # Fail fast on uniqueness issues
  max_unique_retries: 50

  # Smaller data for faster tests
  limits:
    max_array_size: 5
    max_text_length: 100

# =========================================
# Development Environment
# =========================================
development:
  # More realistic data
  default_mode: random

  # Allow more retries during development
  max_unique_retries: 2000

# =========================================
# CI Environment
# =========================================
ci:
  # Test edge cases in CI
  default_mode: mixed

  # Strict limits
  limits:
    max_recursion: 5
    max_array_size: 50

# =========================================
# Production Environment
# =========================================
production:
  # Maximum performance
  fast_mode: true

  # Higher limits for bulk operations
  limits:
    max_array_size: 10000

Programmatic Configuration

You can still configure FakeDataDSL programmatically, which takes precedence over file config:

# File config is loaded first, then this overrides
FakeDataDSL.configure do |config|
  config.default_mode = :edge
  config.limits.max_array_size = 50
end

Disabling Auto-Loading

To prevent automatic config file loading:

# Set before requiring the gem
ENV['FAKE_DATA_DSL_SKIP_CONFIG'] = 'true'
require 'fake_data_dsl'

Or remove/rename the config file.

Best Practices

1. Version Control Your Config

git add config/fake_data_dsl.yml
git commit -m "Add FakeDataDSL configuration"

2. Document Environment Differences

# Test: Fast, small datasets, edge cases
test:
  max_unique_retries: 50  # Fail fast
  limits:
    max_array_size: 5     # Faster tests

3. Use Sensible Defaults

Don't over-configure. The defaults are designed for common use cases.

4. Keep Secrets Out

Config files shouldn't contain secrets. Use environment variables if needed:

# In code, not in config file
FakeDataDSL.configure do |config|
  config.api_key = ENV['FAKE_DATA_API_KEY']
end

Troubleshooting

Config Not Loading

# Check if config file was found
puts FakeDataDSL::ConfigFile.find_config_file
# => nil means no config file found

# Check current configuration
puts FakeDataDSL.configuration.default_mode

Wrong Environment

# Check detected environment
puts ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'

# Force specific environment
FakeDataDSL::ConfigFile.load_and_apply(env: "production")

Invalid YAML

# Bad: Tabs instead of spaces
limits:
    max_array_size: 100  # Tab character causes error

# Good: Use spaces
limits:
  max_array_size: 100    # Spaces work

See Also