Bogus Documentation

Bogus offers several premium NuGet packages for specialized datasets and developer tools. These require a Bogus Premium license.

Available Premium Packages:

• Bogus.Tools.Analyzer: A Roslyn analyzer that detects missing .RuleFor() rules at compile time.
• Bogus.Locations: Provides geographical data including Altitude, AreaCircle (lat/long within radius), Depth, and Geohash.
• Bogus.Healthcare: Industry-specific data for Healthcare, including Drugs (administration, dosage, ingredients), Human (blood type, body parts, diagnosis, pain), Icd9/Icd10 medical codes, and Medical (hospital details, medical phrases).
• Bogus.Hollywood: Entertainment industry data including Movies (actor names, collections, titles) and Tv (networks, series).
• Bogus.Text: Historical texts from the public domain (e.g., Literature like JFK's Inaugural Address or Thomas Paine's Common Sense).

If you prefer not to use the fluent Faker<T> setup, Bogus provides three alternative patterns:

1. Faker Facade: Use a single Faker instance to access various data generators directly.
2. DataSets Directly: Instantiate specific DataSets (like Lorem) and a Randomizer manually.
3. Faker<T> Inheritance: Create a class that inherits from Faker<T> and define rules in the constructor.

// 1. Using the Faker facade
var faker = new Faker("en");
var o = new Order()
{
    OrderId = faker.Random.Number(1, 100),
    Item = faker.Lorem.Sentence()
};

// 2. Using DataSets directly
var random = new Bogus.Randomizer();
var lorem = new Bogus.DataSets.Lorem("en");
var o2 = new Order()
{
    OrderId = random.Number(1, 100),
    Item = lorem.Sentence()
};

// 3. Using Faker<T> inheritance
public class OrderFaker : Faker<Order> {
   public OrderFaker() {
      RuleFor(o => o.OrderId, f => f.Random.Number(1, 100));
      RuleFor(o => o.Item, f => f.Lorem.Sentence());
   }
}
var orderFaker = new OrderFaker();
var o3 = orderFaker.Generate();

The most common way to use Bogus is through the Faker<T> class, which uses a fluent interface to define rules for object properties. You can use RuleFor to map properties to generators, CustomInstantiator for complex initialization, and FinishWith for post-generation actions. You can also set a global Randomizer.Seed to ensure repeatable data sets.

public enum Gender { Male, Female }

// Set the randomizer seed for repeatable data sets
Randomizer.Seed = new Random(8675309);

var fruit = new[] { "apple", "banana", "orange", "strawberry", "kiwi" };
var orderIds = 0;

var testOrders = new Faker<Order>()
    .StrictMode(true)
    .RuleFor(o => o.OrderId, f => orderIds++)
    .RuleFor(o => o.Item, f => f.PickRandom(fruit))
    .RuleFor(o => o.Quantity, f => f.Random.Number(1, 10))
    // Using .OrNull extension from Bogus.Extensions
    .RuleFor(o => o.LotNumber, f => f.Random.Int(0, 100).OrNull(f, .8f));

var userIds = 0;
var testUsers = new Faker<User>()
    .CustomInstantiator(f => new User(userIds++, f.Random.Replace("###-##-####")))
    .RuleFor(u => u.Gender, f => f.PickRandom<Gender>())
    .RuleFor(u => u.FirstName, (f, u) => f.Name.FirstName(u.Gender))
    .RuleFor(u => u.LastName, (f, u) => f.Name.LastName(u.Gender))
    .RuleFor(u => u.UserName, (f, u) => f.Internet.UserName(u.FirstName, u.LastName))
    .RuleFor(u => u.Orders, f => testOrders.Generate(3).ToList())
    .FinishWith((f, u) =>
        {
            Console.WriteLine("User Created! Id={0}", u.Id);
        });

var user = testUsers.Generate();

Bogus allows you to generate the same sequence of data across multiple runs using two strategies:

1. Global Seed

Set the Randomizer.Seed static property. This is easy but can cause 'rippling effects' where adding a new rule shifts the entire sequence for all subsequent data.

2. Local Seed (Recommended)

Use Faker<T>.UseSeed(int) or set the .Random property on a Faker instance or DataSet. This isolates the seed to specific instances, making it ideal for unit tests and preventing schema changes from affecting other data.

Best Practices for Determinism:

• Add new RuleFor rules at the end of the Faker<T> declaration.
• Avoid changing existing rules.
• Always use Faker<T>.UseSeed(int) instead of the global static seed.
• Assert that a value exists (e.g., .NotBeNullOrWhiteSpace()) rather than asserting a specific literal value.

// Global Seed
Randomizer.Seed = new Random(1338);

// Local Seed (Faker<T>)
var orderIds = 0;
var orderFaker = new Faker<Order>()
    .RuleFor(o => o.OrderId, f => orderIds++)
    .RuleFor(o => o.Item, f => f.Commerce.Product())
    .RuleFor(o => o.Quantity, f => f.Random.Number(1, 5));
    
Order SeededOrder(int seed){
   return orderFaker.UseSeed(seed).Generate();
}

var orders = Enumerable.Range(1, 5)
   .Select(SeededOrder)
   .ToList();

// Local Seed (Faker facade)
var faker = new Faker("en")
                {
                   Random = new Randomizer(1338)
                };

Bogus supports F# through the Faker facade and Faker<T> class, working with both immutable records and mutable classes.

// Using Faker facade with immutable records
type Customer = { FirstName : string; LastName : string; Age : int; Title : string }
let f = Faker();

let generator() = 
   { FirstName = f.Name.FirstName()
     LastName  = f.Name.LastName()
     Age       = f.Random.Number(18,60)
     Title     = f.Name.JobTitle() }

// Using Faker<T> with mutable classes
open Bogus
type Customer() = 
  member val FirstName = "" with get, set
  member val LastName = "" with get, set
  member val Age = 0 with get, set
  member val Title = "" with get, set

let faker = 
        Faker<Customer>()
          .RuleFor( (fun c -> c.FirstName), fun (f:Faker) -> f.Name.FirstName() )
          .RuleFor( (fun c -> c.LastName), fun (f:Faker) -> f.Name.LastName() )
          .Rules( fun f c -> 
                    c.Age <- f.Random.Int(18,35) 
                    c.Title <- f.Name.JobTitle() )
  
faker.Generate() |> Dump |> ignore