Installation

pip install fauxfactory

Or with modern package managers:

uv add fauxfactory      # Using uv
poetry add fauxfactory  # Using Poetry

Basic Usage

from fauxfactory import gen_alpha, gen_email, gen_integer, gen_ipaddr

# Generate random data
username = gen_alpha(length=10)          # 'xKjPqRmNoP'
email = gen_email()                      # 'abc@example.com'
age = gen_integer(min_value=18, max_value=100)  # 42
ip = gen_ipaddr()                        # '192.168.1.1'

Simple Data Types

Generate various types of random data with ease:

from fauxfactory import (
    gen_alpha, gen_alphanumeric, gen_email, gen_url,
    gen_ipaddr, gen_mac, gen_date, gen_boolean, gen_uuid
)

# Strings
name = gen_alpha(length=15)
code = gen_alphanumeric(length=8)

# Internet data
email = gen_email()
website = gen_url()
ip_address = gen_ipaddr()
mac_address = gen_mac()

# Other types
birth_date = gen_date()
is_active = gen_boolean()
user_id = gen_uuid()

Structured Data (New!)

Generate complex, nested data structures that mirror real-world scenarios:

Lists

from fauxfactory import gen_list, gen_alpha, gen_email, gen_integer

# Simple list of strings
tags = gen_list(gen_alpha, size=5)
# ['xKjPqR', 'mNoPqR', 'aBcDeF', 'ghIjKl', 'mnOpQr']

# List of dictionaries
users = gen_list({
    'name': gen_alpha,
    'email': gen_email,
    'active': True,
}, size=3)
# [
#     {'name': 'xKjPqR', 'email': 'abc@example.com', 'active': True},
#     {'name': 'mNoPqR', 'email': 'def@example.com', 'active': True},
#     {'name': 'aBcDeF', 'email': 'ghi@example.com', 'active': True},
# ]

Dictionaries

from fauxfactory import gen_dict, gen_alpha, gen_email, gen_integer

# Complex user profile
user = gen_dict({
    'name': gen_alpha,
    'email': gen_email,
    'age': lambda: gen_integer(min_value=18, max_value=100),
    'active': True,
    'preferences': {
        'theme': 'dark',
        'notifications': True,
    },
    'tags': [gen_alpha],
}, list_sizes={'tags': 5})

JSON for API Testing

from fauxfactory import gen_json, gen_alpha, gen_email, gen_integer

# Generate API payload
payload = gen_json({
    'user': {
        'name': gen_alpha,
        'email': gen_email,
    },
    'metadata': {
        'version': '1.0',
        'count': lambda: gen_integer(min_value=1, max_value=100),
    },
}, indent=2)

Validation Support

Many generators support validation to ensure generated data meets your criteria:

from fauxfactory import gen_alpha, gen_email

# Generate username with specific pattern
def is_valid_username(name):
    return name.isalnum() and 3 <= len(name) <= 20

username = gen_alpha(
    length=15,
    validator=is_valid_username,
    default='default_user',
    tries=100
)

# Generate email matching domain pattern
def is_corporate_email(email):
    return email.endswith('@company.com')

email = gen_email(
    validator=is_corporate_email,
    default='user@company.com',
    tries=100
)

E-Commerce Testing

from fauxfactory import gen_dict, gen_alpha, gen_email, gen_integer

# Generate complete order data
order = gen_dict({
    'order_id': lambda: gen_integer(min_value=10000, max_value=99999),
    'customer': {
        'name': gen_alpha,
        'email': gen_email,
    },
    'products': [{
        'sku': lambda: gen_alpha(length=8).upper(),
        'quantity': lambda: gen_integer(min_value=1, max_value=5),
        'price': lambda: gen_integer(min_value=500, max_value=50000) / 100,
    }],
    'status': 'pending',
}, list_sizes={'products': 3})

API Integration Testing

from fauxfactory import gen_json, gen_alpha, gen_email

# Test API with random payloads
payload = gen_json({
    'users': [{
        'name': gen_alpha,
        'email': gen_email,
        'role': 'user',
    }]
}, list_sizes={'users': 5}, indent=2)

response = api_client.post('/users/batch', data=payload)
assert response.status_code == 201

Database Seeding

from fauxfactory import gen_list, gen_alpha, gen_email, gen_boolean

# Generate 100 test users
users = gen_list({
    'username': gen_alpha,
    'email': gen_email,
    'is_active': gen_boolean,
    'role': 'user',
}, size=100)

db.users.insert_many(users)

Pytest Fixtures

import pytest
from fauxfactory import gen_alpha, gen_email, gen_integer

@pytest.fixture
def random_user():
    """Provide fresh random user for each test."""
    return {
        'id': gen_integer(min_value=1, max_value=10000),
        'username': gen_alpha(length=10),
        'email': gen_email(),
    }

def test_user_creation(random_user):
    user = create_user(random_user)
    assert user.username == random_user['username']

Strings

• gen_alpha() - Alphabetic strings

• gen_alphanumeric() - Alphanumeric strings

• gen_numeric_string() - Numeric strings

• gen_utf8() - UTF-8 strings

• gen_latin1() - Latin-1 strings

• gen_cjk() - CJK (Chinese, Japanese, Korean) characters

• gen_cyrillic() - Cyrillic strings

• gen_html() - HTML strings

• gen_special() - Special characters

• gen_lorem_ipsum() - Lorem ipsum text

Numbers

• gen_integer() - Random integers with min/max

• gen_float() - Random floats

Internet

• gen_email() - Email addresses

• gen_url() - URLs

• gen_ipaddr() - IP addresses (IPv4/IPv6)

• gen_mac() - MAC addresses

• gen_netmask() - Network masks

• gen_domain() - Domain names

Dates & Times

• gen_date() - Random dates

• gen_time() - Random times

• gen_datetime() - Random datetimes

Identifiers

• gen_uuid() - UUIDs

Choices

• gen_choice() - Random choice from a list

• gen_boolean() - Random boolean

Structures (New!)

• gen_dict() - Dictionaries from schemas

• gen_json() - JSON from schemas

• gen_list() - Lists from item schemas