Keep the tag of image references pinned by tag and digest

[cristianrgreco]

Summary

ImageName.fromString split name:tag@digest references at the @ first. For mongo:8@sha256:… that gave image = "mongo:8" and tag = "sha256:…": the tag stayed inside the image name and .tag held the digest. .string still round-tripped, so pulling and running worked, but modules that read the version from imageName.tag misbehaved:

• MongoDB: isV5OrLater() returned false, so the health check used the legacy mongo shell. mongo:5+ images don't ship it, so the container never became healthy (the behaviour reported in ImageName.fromString drops the tag of a name:tag@sha256:<digest> reference, so MongoDBContainer picks the legacy mongo shell and never becomes healthy #1468).
• Kafka: satisfies("sha256:…", ">=8.0.0") threw Invalid argument not valid semver in the KafkaContainer constructor.

This PR:

• Splits off the digest first and reads the tag from what precedes it.
• Adds an optional digest constructor argument and public field on ImageName. It is set whenever the reference has a digest, including digest-only references (image@sha256:…). For those, tag still holds the digest, as before.
• Renders string as name:tag@digest when both are present.
• Includes digest in equals.

This follows the Java fix for the same bug (testcontainers/testcontainers-java#11629), where getVersionPart() returns the tag and a new getDigest() returns the digest. Unlike Java, no change to pulling is needed, because Node passes the full imageName.string to dockerode.pull.

Verification

npx vitest run packages/testcontainers/src/container-runtime/image-name.test.ts
npm run format
npm run lint
npm run check-compiles

Test results

Red-green: I ran each test against the pre-fix implementation, then again after the fix.

Test	Before the fix	After the fix
image-name.test.ts: 4 new cases, plus digest checks on existing ones	Failed, e.g. expected 'image:tag' to be 'image'	73/73 pass

During development I also reproduced the module symptoms and confirmed the fix. These tests are not kept in the PR, so CI doesn't pull an extra image:

• Kafka: new KafkaContainer("confluentinc/cp-kafka:6.2.14@sha256:…").withKraft() threw Invalid argument not valid semver before the fix. After it, the error correctly reports version 6.2.14.
• MongoDB: mongo:8.2.12@sha256:e0ce8c… failed with Health check not healthy after 120000ms before the fix and started after it.

format, lint and check-compiles are clean.

Why this is not breaking

• .string, the only value used to pull and inspect images, is unchanged for every reference that already parsed correctly: image, image:tag, image@sha256:…, and references with a registry and port. For name:tag@digest it was already name:tag@digest and still is.
• For digest-only references, tag still returns sha256:….
• The new constructor argument is optional, so existing new ImageName(registry, image, tag) calls still compile and behave the same.
• All existing ImageName tests pass unchanged.
• equals now also compares digest. For names built without a digest, the digest is derived from the tag, so existing comparisons give the same result.

Closes #1468

[netlify]

✅ Deploy Preview for testcontainers-node ready!

Name	Link
🔨 Latest commit	dd0a53b
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-node/deploys/6ab78fb933abe600094a829a
😎 Deploy Preview	https://deploy-preview-1469--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.