feat: return seed value from seed() (#853)

Co-authored-by: ST-DDT <[email protected]>

25 files changed, 136 insertions, 98 deletions

diff --git a/src/faker.ts b/src/faker.ts
index 278e0219..5ae0bd9c 100644
--- a/src/faker.ts
+++ b/src/faker.ts
@@ -14,6 +14,7 @@ import { Git } from './git';
 import { Hacker } from './hacker';
 import { Helpers } from './helpers';
 import { Image } from './image';
+import { deprecated } from './internal/deprecated';
 import { Internet } from './internet';
 import type { KnownLocale } from './locales';
 import { Lorem } from './lorem';
@@ -49,7 +50,7 @@ export class Faker {
 
   readonly definitions: LocaleDefinition = this.initDefinitions();
 
-  seedValue?: number | number[];
+  private _seedValue: number | number[];
 
   readonly fake: Fake['fake'] = new Fake(this).fake;
   readonly unique: Unique['unique'] = new Unique().unique;
@@ -100,6 +101,24 @@ export class Faker {
   }
 
   /**
+   * The seed that was last set.
+   * Please note that generated values are dependent on both the seed and the number of calls that have been made since it was set.
+   *
+   * Use the `seed` function to set a new seed.
+   *
+   * @deprecated Use the return value of `faker.seed()` instead.
+   */
+  public get seedValue(): number | number[] {
+    deprecated({
+      deprecated: 'faker.seedValue',
+      proposed: 'return value of faker.seed()',
+      since: '6.3.0',
+      until: '7.0.0',
+    });
+    return this._seedValue;
+  }
+
+  /**
    * Creates a Proxy based LocaleDefinition that virtually merges the locales.
    */
   private initDefinitions(): LocaleDefinition {
@@ -149,13 +168,81 @@ export class Faker {
     });
   }
 
-  seed(seed?: number | number[]): void {
-    this.seedValue = seed;
+  /**
+   * Sets the seed or generates a new one.
+   *
+   * Please note that generated values are dependent on both the seed and the
+   * number of calls that have been made since it was set.
+   *
+   * This method is intended to allow for consistent values in a tests, so you
+   * might want to use hardcoded values as the seed.
+   *
+   * In addition to that it can be used for creating truly random tests
+   * (by passing no arguments), that still can be reproduced if needed,
+   * by logging the result and explicitly setting it if needed.
+   *
+   * @param seed The seed to use. Defaults to a random number.
+   * @returns The seed that was set.
+   *
+   * @example
+   * // Consistent values for tests:
+   * faker.seed(42)
+   * faker.datatype.number(10); // 4
+   * faker.datatype.number(10); // 8
+   *
+   * faker.seed(42)
+   * faker.datatype.number(10); // 4
+   * faker.datatype.number(10); // 8
+   *
+   * @example
+   * // Random but reproducible tests:
+   * // Simply log the seed, and if you need to reproduce it, insert the seed here
+   * console.log('Running test with seed:', faker.seed());
+   */
+  seed(seed?: number): number;
+  /**
+   * Sets the seed array.
+   *
+   * Please note that generated values are dependent on both the seed and the
+   * number of calls that have been made since it was set.
+   *
+   * This method is intended to allow for consistent values in a tests, so you
+   * might want to use hardcoded values as the seed.
+   *
+   * In addition to that it can be used for creating truly random tests
+   * (by passing no arguments), that still can be reproduced if needed,
+   * by logging the result and explicitly setting it if needed.
+   *
+   * @param seedArray The seed array to use.
+   * @returns The seed array that was set.
+   *
+   * @example
+   * // Consistent values for tests:
+   * faker.seed([42, 13, 17])
+   * faker.datatype.number(10); // 4
+   * faker.datatype.number(10); // 8
+   *
+   * faker.seed([42, 13, 17])
+   * faker.datatype.number(10); // 4
+   * faker.datatype.number(10); // 8
+   *
+   * @example
+   * // Random but reproducible tests:
+   * // Simply log the seed, and if you need to reproduce it, insert the seed here
+   * console.log('Running test with seed:', faker.seed());
+   */
+  seed(seedArray: number[]): number[];
+  seed(
+    seed: number | number[] = Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER)
+  ): number | number[] {
+    this._seedValue = seed;
     if (Array.isArray(seed) && seed.length) {
       this.mersenne.seed_array(seed);
     } else if (!Array.isArray(seed) && !isNaN(seed)) {
       this.mersenne.seed(seed);
     }
+
+    return seed;
   }
 
   /**
diff --git a/test/address.spec.ts b/test/address.spec.ts
index 1569ec85..6965abe8 100644
--- a/test/address.spec.ts
+++ b/test/address.spec.ts
@@ -283,11 +283,8 @@ describe('address', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('countryCode()', () => {
diff --git a/test/animal.spec.ts b/test/animal.spec.ts
index b98aae50..a3ad1af6 100644
--- a/test/animal.spec.ts
+++ b/test/animal.spec.ts
@@ -98,11 +98,8 @@ describe('animal', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       for (const functionName of functionNames) {
diff --git a/test/commerce.spec.ts b/test/commerce.spec.ts
index bb3a2271..87385aa7 100644
--- a/test/commerce.spec.ts
+++ b/test/commerce.spec.ts
@@ -77,11 +77,8 @@ describe('commerce', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe(`color()`, () => {
diff --git a/test/company.spec.ts b/test/company.spec.ts
index cb371751..6ef8b551 100644
--- a/test/company.spec.ts
+++ b/test/company.spec.ts
@@ -86,11 +86,8 @@ describe('company', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('suffixes()', () => {
diff --git a/test/database.spec.ts b/test/database.spec.ts
index 053f91d9..75fe6ac3 100644
--- a/test/database.spec.ts
+++ b/test/database.spec.ts
@@ -62,11 +62,8 @@ describe('database', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('column()', () => {
diff --git a/test/datatype.spec.ts b/test/datatype.spec.ts
index d6034dc7..54504e02 100644
--- a/test/datatype.spec.ts
+++ b/test/datatype.spec.ts
@@ -421,11 +421,8 @@ describe('datatype', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('number', () => {
diff --git a/test/date.spec.ts b/test/date.spec.ts
index 99141a89..4b3350a4 100644
--- a/test/date.spec.ts
+++ b/test/date.spec.ts
@@ -364,11 +364,8 @@ describe('date', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('past()', () => {
diff --git a/test/faker.spec.ts b/test/faker.spec.ts
index 74171210..013f7a4e 100644
--- a/test/faker.spec.ts
+++ b/test/faker.spec.ts
@@ -87,6 +87,28 @@ describe('faker', () => {
   // This is only here for coverage
   // The actual test is in mersenne.spec.ts
   describe('seed()', () => {
+    it('seed()', () => {
+      const seed = faker.seed();
+
+      expect(seed).toBeDefined();
+      expect(seed).toBeTypeOf('number');
+    });
+
+    it('should reset the sequence when calling `seed`', () => {
+      const seed = faker.seed();
+
+      const num1 = faker.datatype.number();
+
+      const newSeed = faker.seed(seed);
+      const num2 = faker.datatype.number();
+
+      expect(num1).toBe(num2);
+      expect(newSeed).toBe(seed);
+
+      const num3 = faker.datatype.number();
+      expect(num1).not.toBe(num3);
+    });
+
     it('seed(number)', () => {
       faker.seed(1);
 
diff --git a/test/finance.spec.ts b/test/finance.spec.ts
index df5a1935..4656e1de 100644
--- a/test/finance.spec.ts
+++ b/test/finance.spec.ts
@@ -121,11 +121,8 @@ describe('finance', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('account()', () => {
@@ -395,9 +392,7 @@ describe('finance', () => {
         });
 
         it('should ignore case for issuer', () => {
-          const seed = faker.seedValue;
-
-          faker.seed(seed);
+          const seed = faker.seed();
           const actualNonLowerCase = faker.finance.creditCardNumber('ViSa');
 
           faker.seed(seed);
diff --git a/test/finance_iban.spec.ts b/test/finance_iban.spec.ts
index 8f72b2dd..a5936faf 100644
--- a/test/finance_iban.spec.ts
+++ b/test/finance_iban.spec.ts
@@ -6,9 +6,6 @@ import ibanLib from '../src/utils/iban';
 const NON_SEEDED_BASED_RUN = 25;
 
 describe('finance_iban', () => {
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe('generic IBAN country checks', () => {
     it.each(ibanLib.formats.map((entry) => entry.country))('%s', (country) => {
       expect(country).toMatch(/^[A-Z]{2}$/);
@@ -20,7 +17,7 @@ describe('finance_iban', () => {
   });
 
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('specific IBAN country checks', () => {
diff --git a/test/git.spec.ts b/test/git.spec.ts
index 18451abd..30c00e8d 100644
--- a/test/git.spec.ts
+++ b/test/git.spec.ts
@@ -98,11 +98,8 @@ describe('git', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('branch()', () => {
diff --git a/test/hacker.spec.ts b/test/hacker.spec.ts
index 89f9d0a6..d0311f72 100644
--- a/test/hacker.spec.ts
+++ b/test/hacker.spec.ts
@@ -105,11 +105,8 @@ describe('name', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('abbreviation()', () => {
diff --git a/test/helpers.spec.ts b/test/helpers.spec.ts
index 3f63a807..95da8302 100644
--- a/test/helpers.spec.ts
+++ b/test/helpers.spec.ts
@@ -490,11 +490,8 @@ describe('helpers', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('randomize()', () => {
diff --git a/test/internet.spec.ts b/test/internet.spec.ts
index 1f870b27..f15692f0 100644
--- a/test/internet.spec.ts
+++ b/test/internet.spec.ts
@@ -123,11 +123,8 @@ describe('internet', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('avatar', () => {
diff --git a/test/lorem.spec.ts b/test/lorem.spec.ts
index 10451632..1338e366 100644
--- a/test/lorem.spec.ts
+++ b/test/lorem.spec.ts
@@ -118,11 +118,8 @@ describe('lorem', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('word()', () => {
diff --git a/test/music.spec.ts b/test/music.spec.ts
index 73457e8d..3fa51b8e 100644
--- a/test/music.spec.ts
+++ b/test/music.spec.ts
@@ -51,11 +51,8 @@ describe('music', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('genre()', () => {
diff --git a/test/name.spec.ts b/test/name.spec.ts
index 91913c55..a182f5f0 100644
--- a/test/name.spec.ts
+++ b/test/name.spec.ts
@@ -163,11 +163,8 @@ describe('name', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('firstName()', () => {
diff --git a/test/phone.spec.ts b/test/phone.spec.ts
index 276272f7..17180156 100644
--- a/test/phone.spec.ts
+++ b/test/phone.spec.ts
@@ -99,11 +99,8 @@ describe('phone', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('phoneNumber()', () => {
diff --git a/test/random.spec.ts b/test/random.spec.ts
index a3c93562..bf081b5c 100644
--- a/test/random.spec.ts
+++ b/test/random.spec.ts
@@ -99,11 +99,8 @@ describe('random', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     describe.each(times(NON_SEEDED_BASED_RUN))('%s', () => {
       describe('arrayElement', () => {
diff --git a/test/system.spec.ts b/test/system.spec.ts
index 492e621d..dc584ee6 100644
--- a/test/system.spec.ts
+++ b/test/system.spec.ts
@@ -83,11 +83,8 @@ describe('system', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('commonFileExt()', () => {
diff --git a/test/time.spec.ts b/test/time.spec.ts
index 82c3fbae..c9b7068d 100644
--- a/test/time.spec.ts
+++ b/test/time.spec.ts
@@ -47,11 +47,8 @@ describe('time', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('recent()', () => {
diff --git a/test/unique.spec.ts b/test/unique.spec.ts
index 07123166..e304092d 100644
--- a/test/unique.spec.ts
+++ b/test/unique.spec.ts
@@ -80,11 +80,8 @@ describe('unique', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('unique()', () => {
diff --git a/test/vehicle.spec.ts b/test/vehicle.spec.ts
index 79731354..d6440814 100644
--- a/test/vehicle.spec.ts
+++ b/test/vehicle.spec.ts
@@ -78,11 +78,8 @@ describe('vehicle', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe('vehicle()', () => {
diff --git a/test/word.spec.ts b/test/word.spec.ts
index d236f564..f3ef451c 100644
--- a/test/word.spec.ts
+++ b/test/word.spec.ts
@@ -177,11 +177,8 @@ describe('word', () => {
     });
   }
 
-  // Create and log-back the seed for debug purposes
-  faker.seed(Math.ceil(Math.random() * 1_000_000_000));
-
   describe(`random seeded tests for seed ${JSON.stringify(
-    faker.seedValue
+    faker.seed()
   )}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
       describe(`adjective`, () => {