diff --git a/docs/guide/usage.md b/docs/guide/usage.md index 48a84fb1e96..26f81c08d22 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -80,6 +80,48 @@ In order to have Faker working properly, you need to check if these `compilerOpt } ``` +## Reproducible results + +Normally Faker will give you different random values each time it is used. + +```ts +faker.music.genre(); // "Soul" +faker.music.genre(); // "Reggae" +``` + +If you want consistent results, you can set your own seed: + +```ts +faker.seed(123); + +const firstRandom = faker.number.int(); + +// Setting the seed again resets the sequence. +faker.seed(123); + +const secondRandom = faker.number.int(); + +console.log(firstRandom === secondRandom); +``` + +::: info NOTE +When upgrading to a new version of Faker, you may get different values for the same seed, as the underlying data (lists of names, words etc) may have changed. +::: + +There are a few methods which use relative dates for which setting a random seed is not sufficient to have reproducible results, for example: `faker.date.past`, `faker.date.future`, `faker.date.birthdate`, `faker.date.recent`, `faker.date.soon` and `faker.git.commitEntry`. This is because these methods default to creating a date before or after "today", and "today" depends on when the code is run. To fix this, you can specify a fixed reference date as a Date or string, for example: + +```ts +// creates a date soon after 2023-01-01 +faker.date.soon({ refDate: '2023-01-01T00:00:00.000Z' }); +``` + +or alternatively you can set a default reference date for all these methods: + +```ts +// affects all future faker.date.* calls +faker.defaultRefDate = '2023-01-01T00:00:00.000Z'; +``` + ## Create complex objects Faker mostly generates values for primitives.