Add support for specifying container hostname (#889)

docs/features/containers.md

@@ -308,6 +308,18 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
+### With custom hostname
+
+**Not recommended.**
+
+See this [Docker blog post on Testcontainers best practices](https://www.docker.com/blog/testcontainers-best-practices/#:~:text=Don't%20hardcode%20the%20hostname)
+
+```javascript
+const container = await new GenericContainer("alpine")
+  .withHostname("my-hostname")
+  .start();
+```
+
 ## Stopping a container
 
 Testcontainers by default will not wait until the container has stopped. It will simply issue the stop command and return immediately. This is to save time when running tests.

packages/testcontainers/src/generic-container/abstract-started-container.ts

@@ -31,6 +31,10 @@ export class AbstractStartedContainer implements StartedTestContainer {
     return this.startedTestContainer.getHost();
   }
 
+  public getHostname(): string {
+    return this.startedTestContainer.getHostname();
+  }
+
   public getFirstMappedPort(): number {
     return this.startedTestContainer.getFirstMappedPort();
   }

packages/testcontainers/src/generic-container/generic-container.test.ts

@@ -534,6 +534,16 @@ describe("GenericContainer", () => {
     await secondStartedContainer.stop();
   });
 
+  it("should set the hostname", async () => {
+    const container = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
+      .withHostname("hostname")
+      .start();
+
+    expect(container.getHostname()).toEqual("hostname");
+
+    await container.stop();
+  });
+
   // failing to build an image hangs within the DockerImageClient.build method,
   // that change might be larger so leave it out of this commit but skip the failing test
   it.skip("should throw an error for a target stage that does not exist", async () => {

packages/testcontainers/src/generic-container/generic-container.ts

@@ -475,4 +475,9 @@ export class GenericContainer implements TestContainer {
     this.logConsumer = logConsumer;
     return this;
   }
+
+  public withHostname(hostname: string): this {
+    this.createOpts.Hostname = hostname;
+    return this;
+  }
 }

packages/testcontainers/src/generic-container/started-generic-container.ts

@@ -89,6 +89,10 @@ export class StartedGenericContainer implements StartedTestContainer {
     return this.host;
   }
 
+  public getHostname(): string {
+    return this.inspectResult.Config.Hostname;
+  }
+
   public getFirstMappedPort(): number {
     return this.boundPorts.getFirstBinding();
   }

packages/testcontainers/src/test-container.ts

@@ -47,6 +47,7 @@ export interface TestContainer {
   withResourcesQuota(resourcesQuota: ResourcesQuota): this;
   withSharedMemorySize(bytes: number): this;
   withLogConsumer(logConsumer: (stream: Readable) => unknown): this;
+  withHostname(hostname: string): this;
 }
 
 export interface RestartOptions {
@@ -63,6 +64,7 @@ export interface StartedTestContainer {
   stop(options?: Partial<StopOptions>): Promise<StoppedTestContainer>;
   restart(options?: Partial<RestartOptions>): Promise<void>;
   getHost(): string;
+  getHostname(): string;
   getFirstMappedPort(): number;
   getMappedPort(port: number): number;
   getName(): string;