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

Co-authored-by: ST-DDT <ST-DDT@gmx.de>

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;
@@ -99,6 +100,24 @@ export class Faker {
     this.localeFallback = opts.localeFallback || 'en';
   }
 
+  /**
+   * 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.
    */
@@ -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;
   }
 
   /**

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()', () => {

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) {

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()`, () => {

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()', () => {

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()', () => {

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', () => {

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()', () => {

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);
 

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);

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', () => {

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()', () => {

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()', () => {

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()', () => {

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', () => {

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()', () => {

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()', () => {

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()', () => {

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()', () => {