feat: only generate IANA example domains

src/modules/internet/module.ts

@@ -540,12 +540,27 @@ export class InternetModule extends ModuleBase {
   /**
    * Generates a random domain name.
    *
+   * @param options The optional options object.
+   * @param options.allowOnlyExamples When `true`, generate a domain under the IANA-reserved example domains (example.com / example.org / example.net) so the result never resolves to a real host. See issue #2228.
+   *
    * @example
    * faker.internet.domainName() // 'slow-timer.info'
+   * faker.internet.domainName({ allowOnlyExamples: true }) // 'slow-timer.example.com'
    *
    * @since 2.0.1
    */
-  domainName(): string {
+  domainName(options?: {
+    /**
+     * When `true`, generate a domain under the IANA-reserved example domains (example.com / example.org / example.net) so the result never resolves to a real host.
+     */
+    allowOnlyExamples?: boolean;
+  }): string {
+    if (options?.allowOnlyExamples) {
+      const word = this.domainWord();
+      const tld = this.faker.helpers.arrayElement(['com', 'org', 'net']);
+      return `${word}.example.${tld}`;
+    }
+
     return `${this.domainWord()}.${this.domainSuffix()}`;
   }
 

test/modules/__snapshots__/internet.spec.ts.snap

@@ -16,7 +16,9 @@ exports[`internet > 42 > displayName > with firstName option 1`] = `"Jane15"`;
 
 exports[`internet > 42 > displayName > with lastName option 1`] = `"Nikita15"`;
 
-exports[`internet > 42 > domainName 1`] = `"hospitable-unit.net"`;
+exports[`internet > 42 > domainName > noArgs 1`] = `"hospitable-unit.net"`;
+
+exports[`internet > 42 > domainName > with allowOnlyExamples 1`] = `"hospitable-unit.example.net"`;
 
 exports[`internet > 42 > domainSuffix 1`] = `"info"`;
 
@@ -134,7 +136,9 @@ exports[`internet > 1211 > displayName > with firstName option 1`] = `"Jane_Fahe
 
 exports[`internet > 1211 > displayName > with lastName option 1`] = `"Dallas_Doe67"`;
 
-exports[`internet > 1211 > domainName 1`] = `"velvety-tarragon.com"`;
+exports[`internet > 1211 > domainName > noArgs 1`] = `"velvety-tarragon.com"`;
+
+exports[`internet > 1211 > domainName > with allowOnlyExamples 1`] = `"velvety-tarragon.example.com"`;
 
 exports[`internet > 1211 > domainSuffix 1`] = `"org"`;
 
@@ -252,7 +256,9 @@ exports[`internet > 1337 > displayName > with firstName option 1`] = `"Jane.Gott
 
 exports[`internet > 1337 > displayName > with lastName option 1`] = `"Elda.Doe"`;
 
-exports[`internet > 1337 > domainName 1`] = `"fatal-co-producer.com"`;
+exports[`internet > 1337 > domainName > noArgs 1`] = `"fatal-co-producer.com"`;
+
+exports[`internet > 1337 > domainName > with allowOnlyExamples 1`] = `"fatal-co-producer.example.com"`;
 
 exports[`internet > 1337 > domainSuffix 1`] = `"com"`;
 

test/modules/internet.spec.ts

@@ -27,7 +27,6 @@ describe('internet', () => {
     t.itEach(
       'protocol',
       'httpMethod',
-      'domainName',
       'domainSuffix',
       'domainWord',
       'ip',
@@ -36,6 +35,9 @@ describe('internet', () => {
       'port',
       'userAgent'
     );
+    t.describe('domainName', (t) => {
+      t.it('noArgs').it('with allowOnlyExamples', { allowOnlyExamples: true });
+    });
 
     t.describe('email', (t) => {
       t.it('noArgs')