Separate testcontainers and modules into workspaces and publish as distinct packages into the testcontainers NPM organisation (#621)

Author: cristianrgreco

.eslintignore

@@ -0,0 +1 @@
+**/build/**

.eslintrc.js

@@ -5,5 +5,6 @@ module.exports = {
   extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended", "plugin:prettier/recommended"],
   rules: {
     "prettier/prettier": "error",
+    "@typescript-eslint/no-empty-function": "off",
   },
 };

.github/workflows/npm-publish.yml

@@ -1,43 +1,48 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-
 name: Node.js Package
 
 on:
   release:
     types: [published]
 
 jobs:
-  commit-version:
+  publish:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v3
         with:
           ref: main
+
       - uses: actions/setup-node@v3
         with:
           node-version: 18
-      - run: |
+
+      - name: Configure Git
+        run: |
           git config user.name github-actions
           git config user.email [email protected]
-          npm --no-git-tag-version version ${{ github.event.release.tag_name }}
+
+      - name: Update versions
+        run: |
+          npm version ${{ github.event.release.tag_name }} -ws
+          for module in src/modules/*; do npm install testcontainers@${{ github.event.release.tag_name }} --save -w $module; done
           sed -i -E "s/(sonar.projectVersion)=.+/\1=${{ github.event.release.tag_name }}/" sonar-project.properties
-          git add package.json package-lock.json sonar-project.properties
+
+      - name: Build packages
+        run: |
+          npm ci --no-optional
+          npm run build -ws
+
+      - name: Git commit and push
+        run: |
+          git add \
+            package-lock.json \
+            src/**/package.json \
+            src/testcontainers/src/version.ts \
+            sonar-project.properties
           git commit -m "${{ github.event.release.tag_name }}"
           git push
 
-  publish-npm:
-    needs: commit-version
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          ref: main
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci --no-optional
-      - run: npm publish
+      - name: Publish packages to NPM
+        run: npm publish -ws
         env:
           NODE_AUTH_TOKEN: ${{ secrets.npm_token }}

.github/workflows/test-main.yml

@@ -126,6 +126,7 @@ jobs:
         run: npm run test:ci -- generic-container.test.ts
 
   rancher-desktop:
+    if: false # https://github.com/rancher-sandbox/rancher-desktop/issues/5285
     runs-on: ${{ matrix.os-version }}
     strategy:
       fail-fast: false
@@ -220,9 +221,11 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Install dependencies
         run: npm ci --omit=optional
+      - name: Build workspaces
+        run: npm run build -ws
       - name: Remove dev dependencies
         run: npm prune --omit=dev
       - name: Run CommonJS module smoke test
-        run: node smoke-test.js
+        run: node src/testcontainers/smoke-test.js
       - name: Run ES module smoke test
-        run: node smoke-test.mjs
+        run: node src/testcontainers/smoke-test.mjs

.github/workflows/test.yml

@@ -120,6 +120,7 @@ jobs:
         run: npm run test:ci -- generic-container.test.ts
 
   rancher-desktop:
+    if: false # https://github.com/rancher-sandbox/rancher-desktop/issues/5285
     runs-on: ${{ matrix.os-version }}
     strategy:
       fail-fast: false
@@ -214,9 +215,11 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Install dependencies
         run: npm ci --omit=optional
+      - name: Build workspaces
+        run: npm run build -ws
       - name: Remove dev dependencies
         run: npm prune --omit=dev
       - name: Run CommonJS module smoke test
-        run: node smoke-test.js
+        run: node src/testcontainers/smoke-test.js
       - name: Run ES module smoke test
-        run: node smoke-test.mjs
+        run: node src/testcontainers/smoke-test.mjs

.gitignore

@@ -1,4 +1,5 @@
-dist/
+build/
+*.tsbuildinfo
 node_modules/
 coverage/
 

.prettierignore

@@ -0,0 +1 @@
+**/build/**

docs/features/compose.md

@@ -43,11 +43,29 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
 
 ### With a pull policy
 
+Testcontainers will automatically pull an image if it doesn't exist. This is configurable:
+
 ```javascript
-const { DockerComposeEnvironment, AlwaysPullPolicy } = require("testcontainers");
+const { DockerComposeEnvironment, PullPolicy } = require("testcontainers");
+
+const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
+  .withPullPolicy(PullPolicy.alwaysPull())
+  .up();
+```
+
+Create a custom pull policy:
+
+```typescript
+const { GenericContainer, ImagePullPolicy } = require("testcontainers");
+
+class CustomPullPolicy implements ImagePullPolicy {
+  public shouldPull(): boolean {
+    return true;
+  }
+}
 
 const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
-  .withPullPolicy(new AlwaysPullPolicy())
+  .withPullPolicy(new CustomPullPolicy())
   .up();
 ```
 

docs/features/containers.md

@@ -21,10 +21,26 @@ const container = await new GenericContainer("alpine:3.10").start();
 Testcontainers will automatically pull an image if it doesn't exist. This is configurable:
 
 ```javascript
-const { GenericContainer, AlwaysPullPolicy } = require("testcontainers");
+const { GenericContainer, PullPolicy } = require("testcontainers");
 
 const container = await new GenericContainer("alpine")
-  .withPullPolicy(new AlwaysPullPolicy())
+  .withPullPolicy(PullPolicy.alwaysPull())
+  .start();
+```
+
+Create a custom pull policy:
+
+```typescript
+const { GenericContainer, ImagePullPolicy } = require("testcontainers");
+
+class CustomPullPolicy implements ImagePullPolicy {
+  public shouldPull(): boolean {
+    return true;
+  }
+}
+
+const container = await new GenericContainer("alpine")
+  .withPullPolicy(new CustomPullPolicy())
   .start();
 ```
 
@@ -395,7 +411,7 @@ import {
 } from "testcontainers";
 
 class CustomContainer extends GenericContainer {
-  protected override async beforeContainerStarted(): Promise<void> {
+  protected override async beforeContainerCreated(): Promise<void> {
     // ...
   }
 

docs/features/images.md

@@ -24,16 +24,33 @@ const container = await GenericContainer
   .build("my-custom-image", { deleteOnExit: false });
 ```
 
-### With pull policy
+### With a pull policy
 
 Testcontainers will automatically pull an image if it doesn't exist. This is configurable:
 
 ```javascript
-const { GenericContainer, AlwaysPullPolicy } = require("testcontainers");
+const { GenericContainer, PullPolicy } = require("testcontainers");
 
 const container = await GenericContainer
   .fromDockerfile("/path/to/build-context")
-  .withPullPolicy(new AlwaysPullPolicy())
+  .withPullPolicy(PullPolicy.alwaysPull())
+  .build();
+```
+
+Create a custom pull policy:
+
+```typescript
+const { GenericContainer, ImagePullPolicy } = require("testcontainers");
+
+class CustomPullPolicy implements ImagePullPolicy {
+  public shouldPull(): boolean {
+    return true;
+  }
+}
+
+const container = await GenericContainer
+  .fromDockerfile("/path/to/build-context")
+  .withPullPolicy(new CustomPullPolicy())
   .build();
 ```