Matriarch Documentation

Welcome to the Matriarch documentation! Matriarch is a powerful ObjectMother library designed to simplify test data generation in Java applications.

What is Matriarch?

Matriarch helps your testing process by generating objects with random values in an easy way, giving you the flexibility to force specific values into defined fields. It’s lightweight, fast, and integrates seamlessly with JUnit.

Key Features

✨ Flexible Object Generation - Create fully populated test objects with random or specified values
🎯 Smart Overrides - Override specific fields using dot notation for nested objects
🔤 Regex Pattern Support - Generate data matching regex patterns with built-in generator
📝 Builder Pattern - Fluent, readable API for test data creation
🧪 JUnit Integration - Seamless integration with JUnit ParameterizedTest
📊 Named Test Cases - Add descriptive names for better test reporting
🎲 Multiple Strategies - Use as builder, factory, or JUnit annotation
⚡ Lightweight - No heavy dependencies, fast test execution
🧩 Custom Field Generators - .forField("field", Supplier<?>) for per-field custom values
🧱 Type-based Generators - .forType(Class<T>, Supplier<T>) to affect all fields of a type
🧭 Known Patterns - Built-in defaults, YAML overrides, and JVM system properties support

Quick Navigation

• Getting Started - Installation and first steps
• Core Concepts - Understand how Matriarch works
• Builder API - Detailed builder pattern usage
• Advanced Usage - Custom generators and complex scenarios
• API Reference - Complete API documentation
• JUnit Integration - Parameterized tests and field injection
• Pattern System - Known patterns and custom patterns
• Built-in Suppliers - 43 ready-to-use data generators
• Examples - Real-world usage examples

Quick Example

// Generate a random user
User user = Mother.forClass(User.class).build();

// Generate with specific values
User admin = Mother.forClass(User.class)
        .forField("email", "admin@example.com")
        .forField("role", "ADMIN")
        .forField("age", 30)
        .build();

// Generate with regex patterns
User user = Mother.forClass(User.class)
        .forField("email", new Regex("[a-z]{5,10}@gmail.com"))
        .forField("phoneNumber", new Regex("\\d{3}-\\d{3}-\\d{4}"))
        .build();

// Collections
List<User> users = Mother.forClass(User.class).buildList(10);

// Use in parameterized tests
@ParameterizedTest
@MotherFactoryResource(args = {
        @RandomArg(
                name = "Valid User",
                targetClass = User.class,
                overrides = @OverrideField(field = "email", value = "[a-z]+@test.com", isRegex = true)
        )
})
void testUser(User user, @Mother Company company) {
    assertTrue(user.getEmail().endsWith("@test.com"));
}

Why Matriarch?

Traditional test data creation can be tedious and repetitive. Matriarch eliminates boilerplate by:

1. Automatic Generation - Generates realistic test data automatically
2. Flexible Overrides - Override only the fields you care about for each test
3. Pattern Matching - Apply consistent patterns across your test suite
4. Type Safety - Fully type-safe API with compile-time checks
5. Easy Integration - Works seamlessly with existing JUnit tests

Getting Help

• Check the API Reference for detailed method documentation
• See Examples for common use cases
• Visit our GitHub repository for source code and issues

Ready to get started? Head over to the Getting Started guide!