rudironsoni Source: kevintsengtw/dotnet-testing-agent-skills (MIT). Ported into dotnet-agent-harness.
AutoFixture and Bogus Integration Application Guide
Applicable Scenarios
Use this skill when asked to perform the following tasks:
- Integrate AutoFixture and Bogus tools
- Create hybrid test data generators
- Design ISpecimenBuilder integrating Bogus data generation
- Create custom AutoData attributes using Bogus
- Handle circular reference issues
- Create unified test data factories
- Design test base classes integrating data generation functionality
Core Concepts
Why Integration is Needed?
AutoFixture Advantages:
- Quickly generate anonymous test data
- Automatically handle complex object structures
- Good circular reference handling mechanism
Bogus Advantages:
- Generate realistic semantic data
- Rich data type support (Email, Phone, Address, etc.)
- Data formats friendly to validation
Integrated Effect:
// Problem before integration
var user = fixture.Create<User>();
// user.Email might be "Email1a2b3c4d", not like a real email
// After integration
var user = integratedFixture.Create<User>();
// user.Email is "john.doe@example.com"
// user.FirstName is "John"
// Other properties automatically filled by AutoFixture
```text
---
## Package Installation
```xml
<PackageReference Include="AutoFixture" Version="4.18.1" />
<PackageReference Include="AutoFixture.Xunit2" Version="4.18.1" />
<PackageReference Include="Bogus" Version="35.6.3" />
<PackageReference Include="xunit" Version="2.9.3" />
<PackageReference Include="AwesomeAssertions" Version="9.1.0" />
```text
---
## Integration Architecture
### Integration Overview
| Integration Method | Applicable Scenario | Complexity |
| ---------------------------- | ----------------------------- | ---------- |
| Property-level SpecimenBuilder | Specific properties using Bogus | Low |
| Type-level SpecimenBuilder | Entire type using Bogus | Medium |
| Hybrid Generator (HybridGenerator) | Unified API integration | Medium |
| Integrated Factory (IntegratedFactory) | Complete test scenario construction | High |
| Custom AutoData Attribute | xUnit integration | Low |
---
## Core Integration Techniques
Implement property-level and type-level integration through the `ISpecimenBuilder` interface, paired with extension methods (`WithBogus()`, `WithOmitOnRecursion()`, `WithSeed()`) to simplify the configuration process. Covers common SpecimenBuilders like Email, Phone, Name, Address, and complete type generator registration patterns.
> For complete content, see [references/core-integration-techniques.md](references/core-integration-techniques.md)
---
## Circular Reference Handling
### Why Circular References are Important?
```csharp
public class User
{
public Company? Company { get; set; } // User references Company
}
public class Company
{
public List<User> Employees { get; set; } = new(); // Company references User
}
```text
**Problem**: User → Company → Employees(User) → Company → ... infinite loop
### Solution: OmitOnRecursionBehavior
```csharp
var fixture = new Fixture();
fixture.Behaviors.OfType<ThrowingRecursionBehavior>()
.ToList()
.ForEach(b => fixture.Behaviors.Remove(b));
fixture.Behaviors.Add(new OmitOnRecursionBehavior());
```text
**Effect**:
- ✅ Avoid StackOverflowException
- ✅ Circular reference properties set to null or empty collection
- ⚠️ Some deep properties may be null (this is expected behavior)
---
## Custom AutoData Attributes
### BogusAutoDataAttribute
```csharp
public class BogusAutoDataAttribute : AutoDataAttribute
{
public BogusAutoDataAttribute()
: base(() => new Fixture().WithBogus())
{
}
}
```text
### Usage
```csharp
[Theory]
[BogusAutoData]
public void UsingIntegratedDataTest(User user, Address address)
{
user.Email.Should().Contain("@");
user.FirstName.Should().NotBeNullOrEmpty();
address.City.Should().NotBeNullOrEmpty();
}
```text
---
## Hybrid Generator
### ITestDataGenerator Interface
```csharp
public interface ITestDataGenerator
{
T Generate<T>();
IEnumerable<T> Generate<T>(int count);
T Generate<T>(Action<T> configure);
}
```text
### HybridTestDataGenerator Implementation
```csharp
public class HybridTestDataGenerator : ITestDataGenerator
{
private readonly IFixture _fixture;
public HybridTestDataGenerator(int? seed = null)
{
_fixture = new Fixture()
.WithBogus()
.WithOmitOnRecursion();
if (seed.HasValue)
{
Bogus.Randomizer.Seed = new Random(seed.Value);
}
}
public T Generate<T>() => _fixture.Create<T>();
public IEnumerable<T> Generate<T>(int count)
=> Enumerable.Range(0, count).Select(_ => Generate<T>());
public T Generate<T>(Action<T> configure)
{
var item = Generate<T>();
configure(item);
return item;
}
}
```text
---
## Integrated Test Data Factory
### IntegratedTestDataFactory
```csharp
public class IntegratedTestDataFactory
{
private readonly IFixture _fixture;
private readonly Dictionary<Type, object> _cache = new();
public IntegratedTestDataFactory(int? seed = null)
{
_fixture = new Fixture()
.WithBogus()
.WithOmitOnRecursion()
.WithRepeatCount(3);
if (seed.HasValue)
{
_fixture.WithSeed(seed.Value);
}
}
public T CreateFresh<T>() => _fixture.Create<T>();
public List<T> CreateMany<T>(int count = 3)
=> _fixture.CreateMany<T>(count).ToList();
public T GetCached<T>() where T : class
{
var type = typeof(T);
if (_cache.TryGetValue(type, out var cached))
return (T)cached;
var instance = CreateFresh<T>();
_cache[type] = instance;
return instance;
}
public void ClearCache() => _cache.Clear();
/// <summary>
/// Create complete test scenario
/// </summary>
public TestScenario CreateTestScenario()
{
var company = CreateFresh<Company>();
var users = CreateMany<User>(5);
var orders = CreateMany<Order>(10);
// Create associations
foreach (var user in users)
{
user.Company = company;
}
company.Employees = users;
return new TestScenario
{
Company = company,
Users = users,
Orders = orders
};
}
}
```text
---
## Test Base Class
### TestBase Implementation
```csharp
public abstract class TestBase
{
protected readonly IFixture Fixture;
protected readonly HybridTestDataGenerator Generator;
protected readonly IntegratedTestDataFactory Factory;
protected TestBase(int? seed = null)
{
Fixture = new Fixture()
.WithBogus()
.WithOmitOnRecursion()
.WithRepeatCount(3);
if (seed.HasValue)
{
Fixture.WithSeed(seed.Value);
}
Generator = new HybridTestDataGenerator(seed);
Factory = new IntegratedTestDataFactory(seed);
}
protected T Create<T>() => Fixture.Create<T>();
protected List<T> CreateMany<T>(int count = 3)
=> Fixture.CreateMany<T>(count).ToList();
protected T Create<T>(Action<T> configure)
{
var instance = Create<T>();
configure(instance);
return instance;
}
}
```text
---
## Seed Management and Reproducibility
### Important Limitations
Since AutoFixture and Bogus have different random number management mechanisms:
- ✅ Seed ensures test behavior stability
- ✅ Seed ensures data format consistency
- ❌ Cannot guarantee all property values are identical
### Recommended Approach
```csharp
// Use Seed to ensure stability
var factory = new IntegratedTestDataFactory(seed: 12345);
// If fully reproducible is needed, use single tool
var faker = new Faker<User>();
faker.UseSeed(12345);
```text
---
## Usage Examples
### Basic Integration Usage
```csharp
[Fact]
public void AutoFixture_Integrated_With_Bogus_Should_Generate_Realistic_Data()
{
// Arrange
var fixture = new Fixture().WithBogus();
// Act
var user = fixture.Create<User>();
// Assert
user.Email.Should().Contain("@");
user.FirstName.Should().NotBeNullOrEmpty();
user.Phone.Should().MatchRegex(@"[\d\-\(\)\s]+");
}
```text
### Using Factory to Create Test Scenarios
```csharp
[Fact]
public void Factory_Should_Create_Complete_Test_Scenario()
{
// Arrange
var factory = new IntegratedTestDataFactory(seed: 42);
// Act
var scenario = factory.CreateTestScenario();
// Assert
scenario.Company.Should().NotBeNull();
scenario.Users.Should().HaveCount(5);
scenario.Orders.Should().HaveCount(10);
scenario.Users.Should().AllSatisfy(user =>
{
user.Company.Should().Be(scenario.Company);
user.Email.Should().Contain("@");
});
}
```text
---
## Best Practices
### Recommended Practices
1. **Always handle circular references first**
```csharp
fixture.WithOmitOnRecursion().WithBogus();
```text
2. **Create dedicated SpecimenBuilders for common entities**
3. **Use Seed to ensure test stability**
4. **Create test base classes to unify data generation logic**
5. **Use cache appropriately to improve performance**
### Things to Avoid
1. ❌ Over-engineering, keep it simple and practical
2. ❌ Expecting integration environment to be fully reproducible
3. ❌ Ignoring circular reference handling
4. ❌ Recreating Fixture in every test
---
## Comparison: Integration vs AutoFixture/Bogus Alone
| Aspect | Pure AutoFixture | Pure Bogus | Integrated Solution |
| ------------------- | ---------------- | -------------- | ------------------- |
| Data Realism | Low | High | High |
| Configuration Complexity | Low | Medium | Medium |
| Object Relationship Handling | Automatic | Manual | Automatic |
| Circular Reference Handling | Built-in | None | Integrated |
| Reproducibility | High | High | Medium |
| Applicable Scenarios | Unit tests | Integration tests/Prototypes | Both |
---
## Reference Resources
### Original Articles
This skill content is distilled from the "Old School Software Engineer's Testing Practice - 30 Day Challenge" article series:
- **Day 15 - AutoFixture and Bogus Integration: Combining Both Advantages**
- Article: https://ithelp.ithome.com.tw/articles/10375620
- Sample Code: https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day15
### Official Documentation
- [AutoFixture GitHub](https://github.com/AutoFixture/AutoFixture)
- [Bogus GitHub Repository](https://github.com/bchavez/Bogus)
---
## Related Skills
- [autofixture-basics](../autofixture-basics/) - AutoFixture basics
- [autofixture-customization](../autofixture-customization/) - AutoFixture customization strategies
- [autodata-xunit-integration](../autodata-xunit-integration/) - AutoData attribute integration
- [bogus-fake-data](../bogus-fake-data/) - Bogus fake data generator