Add never-pull policy

[gologames]

Implements the per-container pull policy discussed in #1455.

Adds PullPolicy.neverPull() for GenericContainer and Docker Compose. Startup fails when a required image is missing locally. Existing pull policies retain their behavior.

Compose uses --pull never --no-build. Dockerfile builds reject this policy because the build API cannot guarantee that base images will not be pulled (docker/buildx#1889). Helper images such as Ryuk are unaffected.

Validation

• Formatting, lint, and cross-module TypeScript checks passed.
• Nearly all CI tests passed, including all core tests covering this change on Node 22 and 24 with Docker and Podman.
• Gcloud and MinIO tests failed due to image pull errors: manifest unknown and access denied, respectively.

CI: https://github.com/gologames/testcontainers-node/actions/runs/34852365970

[netlify]

✅ Deploy Preview for testcontainers-node ready!

Name	Link
🔨 Latest commit	dc7ece9
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-node/deploys/6aa80392ed1bea00082cabe2
😎 Deploy Preview	https://deploy-preview-1460--testcontainers-node.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 18a388da-be1d-4a0a-beeb-01ea749f3bc2

📥 Commits

Reviewing files that changed from the base of the PR and between 99ff0a2 and dc7ece9.

📒 Files selected for processing (15)

• docs/features/compose.md
• docs/features/containers.md
• docs/features/images.md
• packages/testcontainers/fixtures/docker-compose/docker-compose-with-never-pull-build.yml
• packages/testcontainers/fixtures/docker-compose/docker-compose-with-never-pull.yml
• packages/testcontainers/src/docker-compose-environment/docker-compose-environment.test.ts
• packages/testcontainers/src/docker-compose-environment/docker-compose-environment.ts
• packages/testcontainers/src/generic-container/generic-container-builder.ts
• packages/testcontainers/src/generic-container/generic-container-dockerfile.test.ts
• packages/testcontainers/src/generic-container/generic-container.test.ts
• packages/testcontainers/src/generic-container/generic-container.ts
• packages/testcontainers/src/utils/pull-policy.test.ts
• packages/testcontainers/src/utils/pull-policy.ts
• packages/testcontainers/src/utils/test-helper.test.ts
• packages/testcontainers/src/utils/test-helper.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

Summary by CodeRabbit

• New Features

  • Added PullPolicy.neverPull() to use locally available images without pulling them.
  • Added support for custom policies that prevent image pulls.
  • Missing local images now fail clearly instead of being pulled or built automatically.
  • Docker Compose applies never-pull behavior consistently and rejects incompatible build options.

• Bug Fixes

  • Conflicting pull policies are now rejected with a clear error.

• Documentation

  • Documented never-pull behavior, limitations with Dockerfile builds, startup failures, and custom policy rules.

Walkthrough

The pull-policy API now supports PullPolicy.neverPull(). Generic containers inspect local images instead of pulling them, Compose passes --pull never --no-build, Dockerfile builds reject never-pull policies, and tests and documentation cover these behaviors.

Changes

Never-pull policy

Layer / File(s)	Summary
Policy contract and documentation packages/testcontainers/src/utils/pull-policy.ts, packages/testcontainers/src/utils/pull-policy.test.ts, docs/features/*.md	ImagePullPolicy supports neverPull(). resolvePullPolicy() returns never, always, or missing and rejects conflicting predicates. Documentation describes the new policy and Dockerfile limitations.
Generic container pull behavior packages/testcontainers/src/generic-container/*	Generic containers inspect images for never-pull policies and pull only for always. Dockerfile builds reject never-pull policies. Tests cover local, missing, conflicting, and BuildKit cases.
Docker Compose integration packages/testcontainers/src/docker-compose-environment/*, packages/testcontainers/fixtures/docker-compose/*	Compose adds --pull never --no-build, skips explicit pulls, rejects build conflicts, and validates selected services and missing images.
Image-filtered event test support packages/testcontainers/src/utils/test-helper.*	waitForDockerEvent can filter events by image. createTempImageTag creates and cleans up temporary image tags for tests.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant GenericContainer
  participant resolvePullPolicy
  participant DockerRuntimeClient
  GenericContainer->>resolvePullPolicy: Resolve configured policy
  resolvePullPolicy-->>GenericContainer: Return never
  GenericContainer->>DockerRuntimeClient: Inspect local image
  DockerRuntimeClient-->>GenericContainer: Return image status

Loading

Suggested reviewers: cristianrgreco

Merge Risk: ⚪ Minimal · up to dc7ec

The never-pull behavior is covered across container, Dockerfile-build, and Compose paths, with no actionable merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 10 files. (5 skipped: 5…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding a never-pull policy.
Description check	✅ Passed	The description directly explains the never-pull policy, its behavior for containers and Compose, Dockerfile limitations, testing, and known CI failures.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 10 files. (5 skipped: 5 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

packages/testcontainers/src/docker-compose-environment/docker-compose-environment.test.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

packages/testcontainers/src/docker-compose-environment/docker-compose-environment.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

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

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

• 7 others

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit guards the image gate
No pulling paws may pass the plate
Local tags hop into place
Compose tucks its flags in place
Tests count events with careful cheer
Never-pull is safely here}

_{Comment @coderabbitai help to get the list of available commands.}