Add a global never-pull image policy

[longlho]

Add TESTCONTAINERS_PULL_POLICY=never to require local images before registry auth or pulls, including helper containers. Document that builds, Compose, and container networking are outside its scope. Opt-in only; existing policies and defaults are unchanged.

Validation: 8 expected regression failures before the fix; all 13 focused/existing policy tests pass after it. Format, lint, cross-module TypeScript checks, and core build pass.

Closes #1456.

[netlify]

✅ Deploy Preview for testcontainers-node ready!

Name	Link
🔨 Latest commit	42c7675
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-node/deploys/6aa6a94a631d2b00082c9fe6
😎 Deploy Preview	https://deploy-preview-1457--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: 058b2094-ab93-4256-8537-12a5e291d962

📥 Commits

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

📒 Files selected for processing (5)

• docs/configuration.md
• packages/testcontainers/src/container-runtime/clients/image/docker-image-client.test.ts
• packages/testcontainers/src/container-runtime/clients/image/docker-image-client.ts
• packages/testcontainers/src/container-runtime/utils/pull-image.ts
• packages/testcontainers/src/container-runtime/utils/use-local-image.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 support for TESTCONTAINERS_PULL_POLICY=never, allowing Testcontainers to use only images already available locally.
  • Container startup now fails with a clear error when a required image is not available locally.
  • This setting takes precedence over other pull-policy options, including alwaysPull().

• Documentation

  • Added configuration guidance explaining the setting’s behavior and limitations, including that it does not affect network access, Docker builds, or Compose-managed image pulls.

Walkthrough

The change adds TESTCONTAINERS_PULL_POLICY=never. Testcontainers inspects local images before pull operations, reuses available images, and fails when images are unavailable. The behavior applies to both image pull paths and is documented and tested.

Changes

Never-pull image policy

Layer / File(s)	Summary
Local image policy contract packages/testcontainers/src/container-runtime/utils/use-local-image.ts, docs/configuration.md	Adds useLocalImage, which inspects images when the policy is never. Missing images produce an error with the inspection error as its cause. The documentation defines the policy scope and precedence.
Pull path integration packages/testcontainers/src/container-runtime/clients/image/docker-image-client.ts, packages/testcontainers/src/container-runtime/utils/pull-image.ts	Both pull paths check for a local image before force checks, authentication, or image pulls.
Policy behavior validation packages/testcontainers/src/container-runtime/clients/image/docker-image-client.test.ts	Tests cover local reuse, missing images, repeated inspection, preserved causes, and default pulling for both implementations.

Priority: ➖ Normal

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

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Testcontainers
  participant DockerImageClient
  participant pullImage
  participant DockerDaemon
  Testcontainers->>DockerImageClient: Request image pull
  Testcontainers->>pullImage: Request image pull
  DockerImageClient->>DockerDaemon: Inspect local image
  pullImage->>DockerDaemon: Inspect local image
  DockerDaemon-->>DockerImageClient: Image exists or inspection error
  DockerDaemon-->>pullImage: Image exists or inspection error
  DockerImageClient-->>Testcontainers: Reuse image or fail
  pullImage-->>Testcontainers: Reuse image or fail

Loading

Merge Risk: ⚪ Minimal · up to 42c76

The opt-in never-pull policy preserves existing defaults and refuses unavailable images before registry access. No actionable merge risk remains.

🚥 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 2 functions across 4 files. (1 skipped: 1 …	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 describes the main change: adding a global image pull policy that prevents image pulls.
Description check	✅ Passed	The description directly explains the new policy, its scope, preserved behavior, and validation results. It is related to the changeset.
Linked Issues check	✅ Passed	The PR satisfies the coding requirements in [#1456]. useLocalImage activates only for TESTCONTAINERS_PULL_POLICY=never, inspects the local image, and fails before authentication or pull when inspe…
Out of Scope Changes check	✅ Passed	The changes stay within [#1456]. The code changes implement the global image pull policy, the tests verify its pull behavior, and the documentation defines its image-pull-only scope. No unrelated prod…

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 2 functions across 4 files. (1 skipped: 1 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/container-runtime/clients/image/docker-image-client.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/container-runtime/clients/image/docker-image-client.ts

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

packages/testcontainers/src/container-runtime/utils/pull-image.ts

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

• 1 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 checks the image shelf
No registry calls disturb the warren
Local images hop into use
Missing ones leave clear tracks
Two pull paths follow the same rule
Tests guard the policy gate}

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