prusovak2/faker

Bachelors thesis MFF UK

RuleFor()

Nastavení pravidel pro vyplnění položek základních typů. Třeba volat z konstruktoru MyTypeFakeru.

Pro nakonfigurování Fakeru pro svůj typ musí uživatel naimplementovat jednoduchou třídu, která bude potomkem třídy BaseFaker specializované na uživatelem definovaný typ, jehož instance chce plnit pseudonáhodným obsahem (např. MyTypeFaker: BaseFaker<MyType>). Pro vyplnění položek základních datových typů (za které jsou v rámci tohoto projektu považovány byte, sbyte, short, ushort, int, uint, long, ulong, float, double, decimal, char, bool, string, DateTime a Guid) je třeba v konstruktoru MyTypeFakeru třeba volat metodu RuleFor, jejímž prvním parametrem je lambda funkce vracející položku, kterou chceme vyplnit a druhým parametrem lambda funkce na konkrétní metodu na třídě RandomGenerator, jež chceme pro vyplnění položky použít.

public class BasicPersonFaker: BaseFaker<Person>
{
    public BasicPersonFaker()
    {
        RuleFor(person => person.Id, rg => rg.Random.Guid());
        RuleFor(p => p.Age, rg => rg.Random.Int(0, 100));
        RuleFor(p => p.Name, rg => rg.String.Letters(30));
        RuleFor(p => p.IsAwesome, rg => rg.Random.Bool());
    }
}

Generate()

Vytvoření instance uživatelem definované třídy a její vyplnění pseudonáhodným obsahem.

Volána na instanci potomka BaseFakeru specializovaného na konkrétní uživatelem definovaný typ.

BasicPersonFaker basicPersonFaker = new BasicPersonFaker();
Person p = basicPersonFaker.Generate();

Generate(object[] CtorParams)

Vytvoření instance uživatelem definované třídy voláním konstruktoru s konkrétní podobou parametrů a její vyplnění pseudonáhodným obsahem.

Pokud object[] CtorParams obsahuje parametry, které neodpovídají parametrům žádného existujícího konstruktoru na daném typu, vyhodí toto volání metody Generate ArgumentException.

Aby využití Fakeru pro danou uživatelem definovanou třídu nevyžadovalo přítomnost bezparametrického konstruktoru na dané třídě.

Volána na instanci potomka BaseFakeru specializovaného na konkrétní uživatelem definovaný typ.

public class Person
{
    public Person(int age) {
        this.Age = age;
    }
    public Guid Id { get; set; }
    public int Age { get; set; }
    public string Name { get; set; }
    public bool IsAwesome { get; set; }
}

public class PersonFaker: BaseFaker<Person>
{
    public PersonFaker()
    {
        RuleFor(person => person.Id, rg => rg.Random.Guid());
        RuleFor(p => p.Name, rg => rg.String.Letters(30));
        RuleFor(p => p.IsAwesome, rg => rg.Random.Bool());
    }
}

PersonFaker personFaker = new PersonFaker();
//create a person that is 42 years old
Person p = personFaker.Generate(42);

Populate(TClass instance)

Vyplnění již existující instance uživatelem definované třídy pseudonáhodným obsahem.

Obecně je efektivnější vyplňovat metodou Populate již existující instance, neboť se tento přístup vyhýbá volání konstruktoru s přes reflection.

BasicPersonFaker basicPersonFaker = new BasicPersonFaker();
Person AnotherPerson = new Person();
basicPersonFaker.Populate(AnotherPerson);

SetFaker()

Nastavení pravidel pro vyplnění položek jiných než základních typů. Třeba volat z konstruktoru MyTypeFakeru.

Obsahuje-li vyplňovaná třída položky jiného než jednoho ze základních typů, je pro tyto položky možné nastavit InnerFaker voláním metody SetFaker() v konstruktoru faker třídy pro daný typ. Instance Fakeru, specializovaného na typ položky, předaná metodě SetFaker(), je následně využívána pro generování obsahu položky. Kdykoli je zavoláno Generate() či Populate() na Fakeru pro nadřazenou třídu, jsou rekurzivně zavolány i Generate() či Populate() metody na všech InnerFakerech nastavených metodou SetFaker() pro tento vnější Faker. Zda je na InnerFakeru volána Generate či Populate lze nastavit (viz níže).

public class Person
{
    public Address address { get; set; }
    public Guid id { get; set; }
}

public class Address
{
    public int buildingNumber { get; set; }
    public string street { get; set; }
}

public class AddressFaker: BaseFaker<Address>
{
    public AddressFaker()
    {
        RuleFor(a => a.buildingNumber, rg => rg.Random.Int());
        RuleFor(a => a.street, rg => rg.Random.String());
    }
}
public class PersonFaker: BaseFaker<Person>
{
    public PersonFaker()
    {
        SetFaker(p => p.Address, new AddressFaker());
        RuleFor(p => p.id, rg => rg.Random.Guid());
    }
}

FillEmptyMembers flag

Vyplnění položek bez pravidla defaultní randomizační funkcí pro daný typ.

Flag na Fakeru, když je v konstruktoru poděděného Fakeru nastaven na hodnotu UnfilledMembers.DefaultRandomFunc, bude Faker vyplňovat automaticky všechny položky základních typů (viz seznam výše), pro které není specifikováno RuleFor, pomocí defaultní randomizační funkce, kterou RandomGenerator pro daný typ disponuje. Defaultní hodnota této položky je UnfilledMembers.LeaveBlank. Pro snadnou konfiguraci Fakeru bez nutnosti specifikovat mnoho předvídatelných pravidel.

public class SimplePersonFaker : BaseFaker<Person>
{
    public SimplePersonFaker()
    {
        this.FillEmptyMembers = UnfilledMembers.DefaultRandomFunc;
    }
}

CtorUsageFlag

Která z metod Generate(),Generate(object[] CtorParams) či Populate() má být na Fakeru volána, pokud je použit jako InnerFaker?

Tento flag je brán v potaz, když je Faker využit jako InnerFaker. Volá-li uživatel na Fakeru metodu Generate (či jiný ekvivalent) ručně, CtorUsageFlag ani CtorParameters nemají na toto volání žádný vliv.

Nastavován v konstruktoru poděděného Fakeru stejně jako FillEmptyMembers flag.

Je-li zvolena varianta InnerFakerConstructorUsage.GivenParameters, parametry pro konstruktor musí být předány v položce CtorParameters.

Přetížení BaseFaker konstruktoru

Faker lze vytvořit s již existující instancí RandomGeneratoru. Speciálně lze doporučit, aby všechny InnerFakery sdíleli stejnou instanci RandomGeneratoru jako jejich nadřazený Faker a tím byla ušetřena paměť za vícero instancí RandomGeneratoru, viz příklad.

public class ValueClassFakerShared : BaseFaker<ValueClass>
    {
        public ValueClassFakerShared(RandomGenerator random):base(random)
        {
            RuleFor(val => val.Number, rg => rg.Random.IntEven());
            RuleFor(val => val.SmallerNumber, rg => rg.Random.Byte());
        }
    }
    public class StorageFakerShared : BaseFaker<Storage>
    {
        public StorageFakerShared()
        {
            SetFaker(s => s.Value, new ValueClassFakerShared(this.Random));
            RuleFor(s => s.Property, rg => rg.Random.Int(upper: 42));
            RuleFor(s => s.Field, rg => rg.Random.Double());
        }
    }

RandomGenerator lze používat i nezávisle na BaseFaker

RandomGenerator rg = new RandomGenerator(); 
DateTime date = rg.Random.DateTime(new DateTime(2000, 1, 1), new DateTime(2020, 1, 1));
IEnumerable<sbyte>  sbytes = rg.Enumerable.Sbyte(42);
decimal d = rg.Random.Decimal();

RandomEnumerable

Ač jsou generické varianty v současném okamžiku součástí veřejného API, protože je s jejich využitím například možno vytvořit Enumerable náhodných alfanumerických stringů, což současné API jinak neumožňuje, je jejich volání poněkud krkolomné a stojí za uvážení jejich označení jako internal. Jsou však nedocenitelné při implementaci jiných metod na RandomGeneratoru.

Notes

BaseFaker lze specializovat pouze na referenční typy (tedy typy splňující class constraint).

Vyplňovat lze jak properties tak fields, ale pouze pokud jsou veřejné (public).

Metody SetFaker a RuleFor jsou typově bezpečné v tom smyslu, že nelze přiřadit InnerFaker k položce, jsou-li typy nekompatibilní (InnerFaker specializovaný na jiný typ než je typ položky). Stejně tak nelze nastavit metodu vracející typ, co nelze do položky přiřadit, jako RuleFor pro vyplnění dané položky.

Přehled podporovaných náhodných entit

RandomGenerator.

Random.

• Double
• Float
• Decimal
• Int
• Uint
• Short
• Ushort
• Sbyte
• Byte
• Long
• Ulong
• EvenInt
• OddInt
• Bool
• Guid
• DateTime
• Char
• String

Char.

• Char
• Digit
• LowerCaseLetter
• UpperCaseLetter
• Letter
• Alphanumeric
• Ascii
• Vowel - smazat/make internal -v zavislosti na tom, jak bude implementovano lorem ipsum
• Consonant smazat/make internal -v zavislosti na tom, jak bude implementovano lorem ipsum
• HexadecimalDigit
• WhiteSpace

String.

• String
• LowerCaseLetters
• UpperCaseLetters
• Letters
• Aplhanumeric
• Hexadecimal

Enumerable.

• Double
• Float
• Decimal
• Int
• Uint
• Short
• Ushort
• Sbyte
• Byte
• Long
• Ulong
• EvenInt
• OddInt
• Bool
• Guid
• DateTime
• Char
• String

RandomCollection

RandomList

RandomEnumerable

faker's Issues

Nullable varianty základních typů s konfigurovatelnou pravděpodobností výskytu null