testcontainers 8.1.2 → 8.4.0

package/README.md

@@ -18,14 +18,15 @@ npm i -D testcontainers
 
 The following environment variables are supported:
 
-- `DEBUG=testcontainers` See testcontainers logs
-- `DEBUG=testcontainers:containers` See container logs
-- `DEBUG=testcontainers*` See all logs
+- `DEBUG=testcontainers` Enable testcontainers logs
+- `DEBUG=testcontainers:containers` Enable container logs
+- `DEBUG=testcontainers*` Enable all logs
 - `DOCKER_HOST=tcp://docker:2375` Sets the URL of the docker daemon
-- `DOCKER_TLS_VERIFY=1` When set to anything other than an empty string, enables TLS communication with the docker
+- `DOCKER_TLS_VERIFY=1` When set to `1`, enables TLS communication with the docker
   daemon
-- `DOCKER_CERT_PATH=/some/path` Configures the path to the ca.pem, cert.pem, and key.pem files used for TLS
-  verification. Defaults to ~/.docker
+- `DOCKER_CONFIG=/some/path` Configures the path to the `config.json`. Defaults to `~/.docker`
+- `DOCKER_CERT_PATH=/some/path` Configures the path to the `ca.pem`, `cert.pem`, and `key.pem` files used for TLS
+  verification. Defaults to `~/.docker`
 - `TESTCONTAINERS_HOST_OVERRIDE=docker.svc.local` Docker's host on which ports are exposed
 - `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock` Path to Docker's socket. Used by [ryuk](#ryuk) and
   other [auxiliary containers](#auxiliary-containers) that need to perform Docker actions
@@ -300,10 +301,10 @@ expect((await container.exec(["nslookup", "foo"])).exitCode).toBe(0);
 expect((await container.exec(["nslookup", "bar"])).exitCode).toBe(0);
 ```
 
-Specifying a pull policy. Note that if omitted will use the `DefaultPullPolicy` which will use a locally cached image 
-if one already exists, this is usually the preferred option. In cases where there is a local image for a given tag 
-but the remote image with the same tag may have changed (for example when using the `latest` tag), you can tell 
-testcontainers to pull the image again by specifying an `AlwaysPullPolicy`: 
+Specifying a pull policy. Note that if omitted will use the `DefaultPullPolicy` which will use a locally cached image
+if one already exists, this is usually the preferred option. In cases where there is a local image for a given tag
+but the remote image with the same tag may have changed (for example when using the `latest` tag), you can tell
+testcontainers to pull the image again by specifying an `AlwaysPullPolicy`:
 
 ```javascript
 const { GenericContainer, AlwaysPullPolicy } = require("testcontainers");
@@ -325,7 +326,7 @@ const container = await GenericContainer.fromDockerfile(buildContext)
 
 Specifying a default log driver. You can override the logging driver used by Docker to be the default one (json-file).
 This might be necessary when the driver of your docker host does not support reading logs
-and you want to use the `Wait.forLogMessage` wait strategy. This is the same as 
+and you want to use the `Wait.forLogMessage` wait strategy. This is the same as
 [--log-driver json-file on docker run](https://docs.docker.com/config/containers/logging/configure/#configure-the-logging-driver-for-a-container).
 
 ```javascript
@@ -375,8 +376,8 @@ const container = await new GenericContainer("postgres")
   .withExposedPorts(5432)
   .start();
 
-await container.stop({ 
-  timeout: 10000 
+await container.stop({
+  timeout: 10000
 });
 ```
 
@@ -390,7 +391,7 @@ const container = await new GenericContainer("postgres")
   .withExposedPorts(5432)
   .start();
 
-await container.stop({ 
+await container.stop({
   removeVolumes: false
 });
 ```
@@ -432,6 +433,19 @@ const { output } = await container.exec(["curl", `http://host.testcontainers.int
 assert(output === "hello world");
 ```
 
+Specifying an exact host port to bind to (not recommended, Testcontainers will automatically find an available port):
+
+```javascript
+const { GenericContainer } = require("testcontainers");
+
+const container = await new GenericContainer("alpine")
+  .withExposedPorts({
+    container: 8000,
+    host: 8080
+  })
+  .start();
+```
+
 ## Docker Compose
 
 Testcontainers supports docker-compose. For example for the following `docker-compose.yml`:
@@ -547,6 +561,16 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
   .up();
 ```
 
+Specify the [environment file](https://docs.docker.com/compose/environment-variables/#using-the---env-file--option):
+
+```javascript
+const { DockerComposeEnvironment } = require("testcontainers");
+
+const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
+    .withEnvFile(".env.custom")
+    .up();
+```
+
 Specify [profiles](https://docs.docker.com/compose/profiles/):
 
 ```javascript
@@ -557,7 +581,7 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
     .up();
 ```
 
-Specify not to re-create containers that are already running: 
+Specify not to re-create containers that are already running:
 
 ```javascript
 const { DockerComposeEnvironment } = require("testcontainers");
@@ -587,7 +611,7 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
 
 ## Wait Strategies
 
-Ordinarily Testcontainers will wait for up to 60 seconds for the container's mapped network ports to start listening. 
+Ordinarily Testcontainers will wait for up to 60 seconds for the container's mapped network ports to start listening.
 If the default 60s timeout is not sufficient, it can be altered with the `withStartupTimeout()` method:
 
 ```javascript
@@ -641,7 +665,7 @@ credential helpers, credential stores, or raw auth as necessary and in that orde
 
 ## Auxiliary Containers
 
-Testcontainers may need to create auxiliary containers to provide its functionality. 
+Testcontainers may need to create auxiliary containers to provide its functionality.
 
 To avoid Docker pull limits, you can host your own images and use them by setting the appropriate environment variables:
 
@@ -652,21 +676,21 @@ To avoid Docker pull limits, you can host your own images and use them by settin
 
 ### ryuk
 
-Testcontainers will start ryuk whenever a container, docker-compose environment or network is started. 
+Testcontainers will start ryuk whenever a container, docker-compose environment or network is started.
 
-Once started, this container keeps track of containers/images/networks/volumes created by testcontainers and will 
-automatically clean them up 10s after connectivity with testcontainers is lost. This is useful for example if a test 
+Once started, this container keeps track of containers/images/networks/volumes created by testcontainers and will
+automatically clean them up 10s after connectivity with testcontainers is lost. This is useful for example if a test
 starts a container and then terminates unexpectedly, as it will be automatically removed.
 
-ryuk by default does not run privileged, if necessary this can be overridden by setting the environment variable 
-`TESTCONTAINERS_RYUK_PRIVILEGED` to `true`. If necessary, ryuk can be disabled enirely by setting the environment 
+ryuk by default does not run privileged, if necessary this can be overridden by setting the environment variable
+`TESTCONTAINERS_RYUK_PRIVILEGED` to `true`. If necessary, ryuk can be disabled enirely by setting the environment
 variable `TESTCONTAINERS_RYUK_DISABLED` to `true`.
 
 ### SSHd
 
-Testcontainers will start SSHd when using the expose host port functionality. 
+Testcontainers will start SSHd when using the expose host port functionality.
 
-Once started, any container that is created will have a host mapping of `host.testcontainers.internal` that points to 
+Once started, any container that is created will have a host mapping of `host.testcontainers.internal` that points to
 the SSHd container, as well as being connected to its network.
 
 When we then expose a host port, we remote port forward our local port to the SSHd container, which the other
@@ -676,18 +700,17 @@ containers will then be able to access at `host.testcontainers.internal:<exposed
 
 1. **Insufficient Docker memory**
 
-By default, Docker sets CPU and memory limits, with a default memory limit 
-of 2GB. If exceeded, you will be unable to pull/run Docker images. 
+By default, Docker sets CPU and memory limits, with a default memory limit
+of 2GB. If exceeded, you will be unable to pull/run Docker images.
 To see how much memory Docker has  used, you can run ```docker system info```
 
 - To remove existing containers and images to clear some space you can run ```docker system prune```
 - Alternatively you can increase the memory limit via Docker's settings under the Advanced pane.
 
-2. **Insufficient test timeouts** 
+2. **Insufficient test timeouts**
 
-It can take a few seconds up to a few minutes to pull and run certain Docker images, 
+It can take a few seconds up to a few minutes to pull and run certain Docker images,
 depending on file sizes and network constraints. It's unlikely that the default
 timeouts set by test frameworks are sufficient.
 
 - Increase the test timeout via the methods provided by the testing framework.
-

package/dist/bound-ports.d.ts

@@ -1,10 +1,10 @@
-import { Port } from "./port";
+import { Port, PortWithOptionalBinding } from "./port";
 import { InspectResult } from "./docker/functions/container/inspect-container";
 export declare class BoundPorts {
     private readonly ports;
     getBinding(port: Port): Port;
     setBinding(key: Port, value: Port): void;
     iterator(): Iterable<[Port, Port]>;
-    filter(ports: Port[]): BoundPorts;
+    filter(ports: PortWithOptionalBinding[]): BoundPorts;
     static fromInspectResult(inspectResult: InspectResult): BoundPorts;
 }

package/dist/bound-ports.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BoundPorts = void 0;
+const port_1 = require("./port");
 class BoundPorts {
     constructor() {
         this.ports = new Map();
@@ -20,8 +21,9 @@ class BoundPorts {
     }
     filter(ports) {
         const boundPorts = new BoundPorts();
+        const containerPorts = ports.map((port) => port_1.getContainerPort(port));
         for (const [internalPort, hostPort] of this.iterator()) {
-            if (ports.includes(internalPort)) {
+            if (containerPorts.includes(internalPort)) {
                 boundPorts.setBinding(internalPort, hostPort);
             }
         }

package/dist/docker/functions/container/create-container.d.ts

@@ -1,6 +1,6 @@
 import { DockerImageName } from "../../../docker-image-name";
 import Dockerode from "dockerode";
-import { Port } from "../../../port";
+import { PortWithOptionalBinding } from "../../../port";
 import { BindMount, Command, ContainerName, Env, ExtraHost, HealthCheck, NetworkMode, TmpFs } from "../../types";
 export declare type CreateContainerOptions = {
     imageName: DockerImageName;
@@ -8,7 +8,7 @@ export declare type CreateContainerOptions = {
     cmd: Command[];
     bindMounts: BindMount[];
     tmpFs: TmpFs;
-    exposedPorts: Port[];
+    exposedPorts: PortWithOptionalBinding[];
     name?: ContainerName;
     networkMode?: NetworkMode;
     healthCheck?: HealthCheck;

package/dist/docker/functions/container/create-container.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createContainer = void 0;
 const logger_1 = require("../../../logger");
 const docker_client_1 = require("../../docker-client");
+const port_1 = require("../../../port");
 const create_labels_1 = require("../create-labels");
 const createContainer = (options) => __awaiter(void 0, void 0, void 0, function* () {
     try {
@@ -50,7 +51,7 @@ const getEnv = (env) => Object.entries(env).reduce((dockerodeEnvironment, [key,
 const getExposedPorts = (exposedPorts) => {
     const dockerodeExposedPorts = {};
     for (const exposedPort of exposedPorts) {
-        dockerodeExposedPorts[exposedPort.toString()] = {};
+        dockerodeExposedPorts[port_1.getContainerPort(exposedPort).toString()] = {};
     }
     return dockerodeExposedPorts;
 };
@@ -60,7 +61,12 @@ const getExtraHosts = (extraHosts) => {
 const getPortBindings = (exposedPorts) => {
     const dockerodePortBindings = {};
     for (const exposedPort of exposedPorts) {
-        dockerodePortBindings[exposedPort] = [{ HostPort: "0" }];
+        if (port_1.hasHostBinding(exposedPort)) {
+            dockerodePortBindings[exposedPort.container] = [{ HostPort: exposedPort.host.toString() }];
+        }
+        else {
+            dockerodePortBindings[exposedPort] = [{ HostPort: "0" }];
+        }
     }
     return dockerodePortBindings;
 };

package/dist/docker/functions/image/list-images.js

@@ -18,10 +18,12 @@ const listImages = () => __awaiter(void 0, void 0, void 0, function* () {
         const { dockerode } = yield docker_client_1.dockerClient;
         const images = yield dockerode.listImages();
         return images.reduce((dockerImageNames, image) => {
+            var _a;
             if (isDanglingImage(image)) {
                 return dockerImageNames;
             }
-            const dockerImageNamesForImage = image.RepoTags.map((imageRepoTag) => docker_image_name_1.DockerImageName.fromString(imageRepoTag));
+            const repoTags = (_a = image.RepoTags) !== null && _a !== void 0 ? _a : [];
+            const dockerImageNamesForImage = repoTags.map((imageRepoTag) => docker_image_name_1.DockerImageName.fromString(imageRepoTag));
             return [...dockerImageNames, ...dockerImageNamesForImage];
         }, []);
     }

package/dist/docker-compose-environment/docker-compose-environment.d.ts

@@ -8,6 +8,7 @@ export declare class DockerComposeEnvironment {
     private projectName;
     private build;
     private recreate;
+    private envFile;
     private profiles;
     private env;
     private waitStrategy;
@@ -15,6 +16,7 @@ export declare class DockerComposeEnvironment {
     constructor(composeFilePath: string, composeFiles: string | string[], uuid?: Uuid);
     withBuild(): this;
     withEnv(key: EnvKey, value: EnvValue): this;
+    withEnvFile(envFile: string): this;
     withProfiles(...profiles: string[]): this;
     withNoRecreate(): this;
     withWaitStrategy(containerName: string, waitStrategy: WaitStrategy): this;

package/dist/docker-compose-environment/docker-compose-environment.js

@@ -30,6 +30,7 @@ class DockerComposeEnvironment {
     constructor(composeFilePath, composeFiles, uuid = new uuid_1.RandomUuid()) {
         this.build = false;
         this.recreate = true;
+        this.envFile = "";
         this.profiles = [];
         this.env = {};
         this.waitStrategy = {};
@@ -46,6 +47,10 @@ class DockerComposeEnvironment {
         this.env[key] = value;
         return this;
     }
+    withEnvFile(envFile) {
+        this.envFile = envFile;
+        return this;
+    }
     withProfiles(...profiles) {
         this.profiles = profiles;
         return this;
@@ -80,6 +85,9 @@ class DockerComposeEnvironment {
                 commandOptions.push("--no-recreate");
             }
             const composeOptions = [];
+            if (this.envFile) {
+                composeOptions.push("--env-file", this.envFile);
+            }
             this.profiles.forEach((profile) => composeOptions.push("--profile", profile));
             yield docker_compose_up_1.dockerComposeUp(Object.assign(Object.assign({}, options), { commandOptions, composeOptions, env: this.env }), services);
             const startedContainers = (yield list_containers_1.listContainers()).filter((container) => container.Labels["com.docker.compose.project"] === this.projectName);

package/dist/generic-container/generic-container.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import archiver from "archiver";
 import { BoundPorts } from "../bound-ports";
-import { Port } from "../port";
+import { PortWithOptionalBinding } from "../port";
 import { PullPolicy } from "../pull-policy";
 import { StartedTestContainer, TestContainer } from "../test-container";
 import { WaitStrategy } from "../wait-strategy";
@@ -16,7 +16,7 @@ export declare class GenericContainer implements TestContainer {
     protected env: Env;
     protected networkMode?: NetworkMode;
     protected networkAliases: string[];
-    protected ports: Port[];
+    protected ports: PortWithOptionalBinding[];
     protected cmd: Command[];
     protected bindMounts: BindMount[];
     protected name?: ContainerName;
@@ -42,8 +42,8 @@ export declare class GenericContainer implements TestContainer {
     withNetworkMode(networkMode: NetworkMode): this;
     withNetworkAliases(...networkAliases: string[]): this;
     withExtraHosts(...extraHosts: ExtraHost[]): this;
-    withExposedPorts(...ports: Port[]): this;
-    protected addExposedPorts(...ports: Port[]): this;
+    withExposedPorts(...ports: PortWithOptionalBinding[]): this;
+    protected addExposedPorts(...ports: PortWithOptionalBinding[]): this;
     withBindMount(source: Dir, target: Dir, bindMode?: BindMode): this;
     withHealthCheck(healthCheck: HealthCheck): this;
     withStartupTimeout(startupTimeout: number): this;

package/dist/port.d.ts

@@ -1,2 +1,9 @@
 export declare type Port = number;
 export declare type PortString = string;
+export declare type PortWithBinding = {
+    container: Port;
+    host: Port;
+};
+export declare type PortWithOptionalBinding = Port | PortWithBinding;
+export declare const getContainerPort: (port: PortWithOptionalBinding) => number;
+export declare const hasHostBinding: (port: PortWithOptionalBinding) => port is PortWithBinding;

package/dist/port.js

@@ -1,2 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasHostBinding = exports.getContainerPort = void 0;
+const getContainerPort = (port) => typeof port === "number" ? port : port.container;
+exports.getContainerPort = getContainerPort;
+const hasHostBinding = (port) => {
+    return typeof port === "object" && port.host !== undefined;
+};
+exports.hasHostBinding = hasHostBinding;

package/dist/reaper.js

@@ -16,6 +16,7 @@ const generic_container_1 = require("./generic-container/generic-container");
 const session_id_1 = require("./docker/session-id");
 const docker_client_1 = require("./docker/docker-client");
 const images_1 = require("./images");
+const port_1 = require("./port");
 class RealReaper {
     constructor(container, socket) {
         this.container = container;
@@ -106,7 +107,7 @@ class ReaperInstance {
                 }
             });
             return new Promise((resolve) => {
-                socket.connect(port, host, () => {
+                socket.connect(port_1.getContainerPort(port), host, () => {
                     logger_1.log.debug(`Connected to Reaper ${containerId}`);
                     socket.write(`label=org.testcontainers.session-id=${session_id_1.sessionId}\r\n`);
                     const reaper = new RealReaper(startedContainer, socket);

package/dist/registry-auth-locator/index.js

@@ -21,7 +21,8 @@ const creds_store_1 = require("./creds-store");
 const auths_1 = require("./auths");
 const logger_1 = require("../logger");
 const DEFAULT_REGISTRY = "https://index.docker.io/v1/";
-const dockerConfigFile = path_1.default.resolve(os_1.default.homedir(), ".docker", "config.json");
+const dockerConfigLocation = process.env.DOCKER_CONFIG || `${os_1.default.homedir()}/.docker`;
+const dockerConfigFile = path_1.default.resolve(dockerConfigLocation, "config.json");
 const readDockerConfig = () => __awaiter(void 0, void 0, void 0, function* () {
     if (!fs_1.existsSync(dockerConfigFile)) {
         return Promise.resolve({});

package/dist/test-container.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { Port } from "./port";
+import { Port, PortWithOptionalBinding } from "./port";
 import { PullPolicy } from "./pull-policy";
 import { WaitStrategy } from "./wait-strategy";
 import { Readable } from "stream";
@@ -9,7 +9,7 @@ export interface TestContainer {
     withEnv(key: EnvKey, value: EnvValue): this;
     withCmd(cmd: Command[]): this;
     withTmpFs(tmpFs: TmpFs): this;
-    withExposedPorts(...ports: Port[]): this;
+    withExposedPorts(...ports: PortWithOptionalBinding[]): this;
     withBindMount(source: Dir, target: Dir, bindMode: BindMode): this;
     withWaitStrategy(waitStrategy: WaitStrategy): this;
     withStartupTimeout(startupTimeout: number): this;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "testcontainers",
   "author": "Cristian Greco",
-  "version": "8.1.2",
+  "version": "8.4.0",
   "main": "dist/index",
   "types": "dist/index",
   "keywords": [
@@ -33,11 +33,11 @@
   },
   "dependencies": {
     "@types/archiver": "^5.1.1",
-    "@types/dockerode": "^3.2.5",
+    "@types/dockerode": "^3.2.7",
     "archiver": "^5.3.0",
     "byline": "^5.0.0",
-    "debug": "^4.3.2",
-    "docker-compose": "^0.23.13",
+    "debug": "^4.3.3",
+    "docker-compose": "^0.23.17",
     "dockerode": "^3.3.1",
     "get-port": "^5.1.1",
     "glob": "^7.2.0",
@@ -51,10 +51,10 @@
     "@types/byline": "^4.2.33",
     "@types/debug": "4.1.7",
     "@types/glob": "^7.1.4",
-    "@types/jest": "^27.0.2",
+    "@types/jest": "^27.0.3",
     "@types/node": "^16.9.6",
-    "@types/node-fetch": "^2.5.11",
-    "@types/pg": "^8.6.1",
+    "@types/node-fetch": "^2.5.12",
+    "@types/pg": "^8.6.4",
     "@types/properties-reader": "^2.1.1",
     "@types/tar-fs": "^2.0.1",
     "@typescript-eslint/eslint-plugin": "^4.31.2",
@@ -63,17 +63,17 @@
     "cross-env": "^7.0.3",
     "eslint": "^7.32.0",
     "eslint-config-prettier": "^8.3.0",
-    "husky": "^7.0.2",
-    "jest": "^27.2.1",
+    "husky": "^7.0.4",
+    "jest": "^27.2.5",
     "kafkajs": "^1.15.0",
-    "lint-staged": "^11.1.2",
-    "mysql2": "^2.3.0",
-    "neo4j-driver": "^4.3.3",
-    "node-fetch": "^2.6.1",
-    "pg": "^8.7.1",
+    "lint-staged": "^11.1.4",
+    "mysql2": "^2.3.3",
+    "neo4j-driver": "^4.3.6",
+    "node-fetch": "^2.6.7",
+    "pg": "^8.7.3",
     "prettier": "^2.4.1",
     "rimraf": "^3.0.2",
-    "ts-jest": "^27.0.5",
+    "ts-jest": "^27.0.7",
     "ts-node": "^10.2.1",
     "typescript": "^4.3.5",
     "wait-for-expect": "^3.0.2"