skip to content

Why do tests built on Bogus data sometimes fail only on the build server, and how do UseSeed and UseDateTimeReference make Faker<T> output repeatable?

level: middleimportance: should knowfreq 35%

answer

  1. random by default, every run
  2. global Randomizer.Seed vs local seed
  3. UseSeed(int) per Faker<T>
  4. dates are relative to now
  5. log the seed, assert behaviour

basics

~20 s

Bogus draws from a fresh random sequence each run and dates from the current clock, so a rare value can break a test once in fifty runs. UseSeed(int) fixes a Faker<T>'s sequence and UseDateTimeReference fixes its clock, making failures reproducible.

solid answer

~40 s

Without a seed every run of a `Faker<Patient>` produces different data, so a test that breaks on an apostrophe in a surname or a 2,000-character name fails rarely and cannot be replayed. `Faker<T>.UseSeed(int)` gives that faker its own `Randomizer` seeded with the value; the global static `Randomizer.Seed` is then ignored for it. Date methods such as `f.Date.Past()` are relative to the current clock, so I also call `UseDateTimeReference(new DateTime(2026, 1, 1))`. Three things still break repeatability: values created outside `f`, such as `Guid.NewGuid()`; a shared faker whose sequence depends on how many objects earlier tests generated; and adding or reordering rules, or upgrading Bogus's major version, which shifts the sequence. So I seed per test or per faker, log the seed when a test fails, and assert behaviour rather than literal generated values.

code

csharp · 16 lines
csharp
public sealed class SchedulingTests(ITestOutputHelper output)
{
    [Fact]
    public void Books_first_free_slot()
    {
        var seed = Random.Shared.Next();
        output.WriteLine($"Bogus seed: {seed}");    // replay with this value

        var patient = PatientFakers.Default.Clone()
            .UseSeed(seed)
            .UseDateTimeReference(new DateTime(2026, 1, 1))
            .Generate();

        // act and assert on scheduling behaviour, not on patient.FirstName
    }
}

go deeper

for a junior

Remember the two calls: UseSeed(int) for the random sequence and UseDateTimeReference(DateTime) for the clock that date rules use.

for a middle

Explain local versus global seeds, why values created outside the f hub ignore the seed, and why a shared faker's output depends on test order.

for a senior

Make flaky data failures replayable: log the seed, reseed per test, keep assertions on behaviour, and treat Bogus major upgrades as output changes.

for a principal

Choose a seeding policy for the whole suite, fixed for snapshot-style tests and random-but-logged elsewhere, and make it part of the test conventions.

## Where the randomness comes from Every data set in Bogus draws numbers from a `Randomizer`. Unless told otherwise, a new `Faker<T>` uses the global static `Randomizer.Seed`, a `System.Random` created once per process with no fixed seed. Two consequences follow: - each test run sees **different** patients, which is good for finding edge cases and bad for reproducing them; - date methods (`Past`, `Recent`, `Soon`, `Future`, and their `DateOnly` versions) default to a reference of **now**, so even with a fixed seed a date of birth drifts every day. A scheduling test that fails when a generated appointment lands on a weekend, or when a surname contains an apostrophe, fails once in a while on the build server and passes on every local rerun. ## Two ways to fix the sequence | | Global seed | Local seed | |---|---|---| | Code | `Randomizer.Seed = new Random(1338);` | `new Faker<Patient>().UseSeed(1338)` | | Scope | every faker created afterwards, process-wide | that faker only | | Sensitive to | every other test that generates data | changes to that faker's own rules | | README advice | quick setup | preferred for unit tests | `UseSeed(int)` stores the seed and gives the faker's hub `new Randomizer(seed)`; when a local seed is set, the global source is ignored. The plain `Faker` hub can be seeded the same way by setting its `Random` property to `new Randomizer(seed)`. Setting the global seed in one test class while xUnit runs another class in parallel is particularly fragile: both draw from the same static source, so neither sequence is stable. ## Fixing the clock ```csharp var patients = new Faker<Patient>() .UseSeed(4242) .UseDateTimeReference(new DateTime(2026, 1, 1)) .RuleFor(p => p.DateOfBirth, f => f.Date.PastDateOnly(90)); ``` `UseDateTimeReference` anchors every date calculation of this faker to the given moment, unless a method is passed its own `refDate`. With both a seed and a reference, the same patients come out on every machine and every day. ## What still breaks repeatability 1. **Values made outside the hub.** A rule `f => Guid.NewGuid()` or `f => DateTime.UtcNow` ignores the seed. Use `f.Random.Guid()` and the date data set instead. 2. **Shared, stateful fakers.** A seeded faker continues its sequence across calls. If a static faker serves many tests, the patient a test receives depends on how many patients earlier tests generated, which depends on test order. Call `UseSeed` at the start of each test, or give each test its own faker. 3. **Rule changes.** Each rule consumes numbers from the sequence, so inserting a rule shifts every value after it. Bogus's README advises adding new rules last and not changing existing ones. 4. **Library upgrades.** Bogus's README calls a change to deterministic output a breaking change and says the project generally follows semantic versioning, so a new major version can change outputs; locale data updates are a typical cause. ## Making a failure replayable - Pick the seed per test (fixed, or random and then **logged** in the failure message or test output). - When a test fails on the build server, rerun it locally with the logged seed to get the same patients. - Keep assertions about behaviour: "the scheduler refused the overlapping slot", not "the patient is called Maribel". The README's own advice is to assert that a value exists rather than its literal content, so outputs can change across versions without breaking tests. ## Why not always seed? A fixed seed makes every run test the same data, which hides the rare edge case random data exists to find. A common compromise in an ASP.NET Core suite is a fixed seed for tests that compare snapshots or exact output, and a random but logged seed for the rest. ## A checklist for the clinic suite 1. Every faker that feeds an assertion-sensitive test calls `UseSeed` and `UseDateTimeReference`. 2. No rule calls `Guid.NewGuid()`, `DateTime.Now` or `Random.Shared`; the hub's `f.Random` and `f.Date` replace them. 3. Shared fakers are cloned per test, so one test's generation does not shift another's sequence. 4. A failing test prints its seed, and the test can be rerun with that seed pinned. 5. Upgrading Bogus across a major version is reviewed like any change that can alter test data.

  • Two test classes set Randomizer.Seed to the same value, yet their data differs between runs. Why?
    `Randomizer.Seed` is one process-wide `Random`, and xUnit runs test classes in parallel by default. Both classes draw from the same sequence in an interleaving that changes from run to run, so neither sees a stable stream. Use `UseSeed` on each faker, which gives it a private `Randomizer`.
  • A seeded faker produced different patients after a teammate added a rule for MiddleName. Is that a bug?
    No. Each rule consumes values from the seeded sequence in declaration order, so a new rule in the middle shifts everything generated after it. Bogus's README recommends adding rules last and not editing existing ones when tests depend on deterministic output, and asserting on presence rather than exact values.

  • A Bogus seed makes Guid.NewGuid() inside a rule repeatable too.
  • Setting Randomizer.Seed in one test class is safe while other classes run in parallel.
  • UseSeed alone makes f.Date.Past() return the same dates on every day.
  • Seeded Bogus output never changes when you upgrade to a new major version.
  • A seeded static faker gives each test the same patient regardless of test order.