AutoBogus

A C# library complementing the Bogus generator by adding auto creation and population capabilities.

The following packages are available for download from NuGet:

• AutoBogus
• AutoBogus.Conventions
• AutoBogus.FakeItEasy
• AutoBogus.Moq
• AutoBogus.NSubstitute

Configuration

There are several levels of configuration available.

• Global

  > this is scoped as the default configuration across all generate requests.

• Faker

  > this is scoped as the configuration applied to all generate requests for an

  AutoFaker

  instance.

• Generate

  > this is scoped as the configuration for a specific generate request.

The above levels are hierarchical and in the order listed. Therefore, if a setting is not set for a

Generate

Faker

Global

Builder

A configuration is defined via a builder action that invokes the relevant setup method.

// Configure globally
AutoFaker.Configure(builder =>
{
  builder
    .WithLocale()           // Configures the locale to use
    .WithRepeatCount()      // Configures the number of items in a collection
    .WithDataTableRowCount()    // Configures the number of data table rows to generate
    .WithRecursiveDepth()   // Configures how deep nested types should recurse
    .WithTreeDepth()        // Configures the tree depth of an object graph
    .WithBinder()           // Configures the binder to use
    .WithFakerHub()         // Configures a Bogus.Faker instance to be used - instead of a default instance
    .WithSkip()             // Configures members to be skipped for a type
    .WithOverride();        // Configures the generator overrides to use - can be called multiple times
});

// Configure a faker
var faker = AutoFaker.Create(builder => ...);
// Configure a generate request
faker.Generate(builder => ...);
faker.Generate(builder => ...);
AutoFaker.Generate(builder => ...);
AutoFaker.Generate(builder => ...);
// Configure an AutoFaker 
var personFaker = new AutoFaker()
  .Configure(builder => ...)
  .RuleFor(fake => fake.Id, fake => fake.Random.Int())
  .Generate();

The

Generate()

WithArgs()

TFaker

Usage

AutoFaker

The non-generic

AutoFaker

It can be used statically or as a configured instance. The static methods provide a means of quickly generating types on-the-fly and the instance can be reused across multiple generate requests.

Static

AutoFaker.Generate();
AutoFaker.Generate();

Instance

var faker = AutoFaker.Create();

faker.Generate();
faker.Generate();

AutoFaker<T>

The

AutoFaker

var personFaker = new AutoFaker()
  .RuleFor(fake => fake.Id, fake => fake.Random.Int())
  .RuleSet("empty", rules =>
  {
    rules.RuleFor(fake => fake.Id, () => 0);
  });

// Use explicit conversion or call Generate()
var person1 = (Person)personFaker;
var person2 = personFaker.Generate();
person1.Dump();
person2.Dump();
// An existing instance can also be populated
var person3 = new Person();
personFaker.Populate(person3);
person3.Dump();

When the

AutoFaker

AutoFaker

Generate()

public class PersonFaker : AutoFaker
{
  public PersonFaker(int id)
  {
    RuleFor(fake => fake.Id, () => id)
  }
}

var id = AutoFaker.Generate();
// Create an instance and call Generate()
var personFaker = new PersonFaker(id);
var person1 = personFaker.Generate();
person1.Dump();
// Create a Person instance using AutoFaker.Generate()
// If the AutoFaker class needs constructor arguments, they can be passed using WithArgs()
var person2 = AutoFaker.Generate(builder => builder.WithArgs(id));
person2.Dump();

Note that, should a rule set be used to generate a type, then only members not defined in the rule set are auto generated. In the examples above, the

Id

RuleFor

Binders

A default

IAutoBinder

• AutoBogus.FakeItEasy
• AutoBogus.Moq
• AutoBogus.NSubstitute

Skipping

The generating of values can be skipped based on either a type or the member path of a type.

AutoFaker.Configure(builder =>
{
  // Types
  builder
    .WithSkip
()                      // Define a generic type
    .WithSkip(typeof(Country));               // Define a type

  // Type members
  builder
    .WithSkip(person => person.Name); // Define using an expression for public members
    .WithSkip("Age");                 // Define using a string for protected, internal, etc. members
    .WithSkip(typeof(Person), "Gender");      // Define using a string for protected, internal, etc. members
});

Overrides

In some cases, custom rules are needed to generate a type and for this, AutoBogus provides generator overrides. By implementating a class that inherits

AutoGeneratorOverride

public class PersonOverride : AutoGeneratorOverride
{
  public override bool CanOverride(AutoGenerateContext context)
  {
    return context.GenerateType == typeof(Person);
  }

  public override void Generate(AutoGenerateOverrideContext context)
  {
    // Apply an email value to the person
    var person = context.Instance as Person;
    person.Email = context.Faker.Internet.Email();
  }
}
// Register the override
AutoFaker.Configure(builder => builder.WithOverride(new PersonOverride()));

Note that a virtual

Preinitialize

Behaviors

The following underlying behaviors are in place in AutoBogus:

• Interface and abstract class types are not auto generated - they will result in

  null

  values. A custom binder would be needed, like one of the packages listed above.
• Rescursive types - a nested member with the same parent type - will be generated to 2 levels by default to avoid a

  StackOverflowException

  -

  Person.Parent -> Person.Parent -> null

• Read only properties - if a property is read only but can be resolved as an

  ICollection<>

  or

  IDictionary

  , then it will be populated via the

  Add()

  method.

Conventions

The AutoBogus.Conventions package provides conventions for generating values, currently based on generation type and name. As an example, a property named

Email

string

Faker.Internet.Email()

To include the conventions in your project, apply the following configuration at the required level:

AutoFaker.Configure(builder =>
{
  builder.WithConventions();
});

Each convention generator maps to a Bogus generator method and can be configured individually.

AutoFaker.Configure(builder =>
{
  builder.WithConventions(config =>
  {
    config.FirstName.Enabled = false;      // Disables the FirstName generator
    config.LastName.AlwaysGenerate = true; // Overrides any LastName values previously generated
    config.Email.Aliases("AnotherEmail");  // Generates an email value for members named AnotherEmail
  });
});

Templating

The AutoBogus.Templating package allows value generation rules to be defined using a text based templating notation.

This can be used by using the

GenerateWithTemplate()

public class Person
{
  public int Id { get; set; }
  public string FirstName { get; set; }
  public string LastName { get; set; }
  public string Status { get; set; } // Will be auto generated by the underlying AutoBogus generator
}

var persons = new AutoFaker().GenerateWithTemplate(@"
  Id | FirstName | LastName
  0  | John      | Smith
  1  | Jane      | Jones
  2  | Bob       | Clark
");

Contributors

Made with contributors-img.