Merge main and address healthcheck review feedback

Author: cristianrgreco

.github/workflows/close-inactive-issues.yml

@@ -0,0 +1,24 @@
+name: Close inactive issues
+
+on:
+  schedule:
+    - cron: "30 1 * * *"
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-22.04
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v10
+        with:
+          days-before-issue-stale: 90
+          days-before-issue-close: 30
+          stale-issue-label: "stale"
+          exempt-issue-labels: "never-stale"
+          stale-issue-message: "This issue is stale because it has been open for 90 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 30 days since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/dependency-review.yml

@@ -7,7 +7,7 @@ permissions:
 jobs:
   dependency-review:
     name: Run
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: "Checkout Repository"
         uses: actions/checkout@v5

.github/workflows/test-template.yml

@@ -54,6 +54,6 @@ jobs:
           workspace: "${{ inputs.workspace }}"
 
       - name: Run tests
-        run: npm run test:ci -- --coverage.include=${{ steps.npm-install.outputs.workspace_path }} ${{ steps.npm-install.outputs.workspace_path }}
+        run: npm run test:ci -- --coverage.include="${{ steps.npm-install.outputs.workspace_path }}/**/*.ts" ${{ steps.npm-install.outputs.workspace_path }}
         env:
           CI: true

AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md
+
+## Purpose
+
+This is a working guide for contributors and coding agents in this repository.
+It captures practical rules that prevent avoidable CI and PR churn.
+
+## Instruction precedence
+
+- Repository-specific instructions in this file override generic coding-agent defaults, skills, and templates.
+- If a generic workflow conflicts with this file, follow this file.
+
+## Repository Layout
+
+- This repository is an npm workspaces monorepo.
+  - root package: `testcontainers-monorepo`
+  - workspaces: `packages/testcontainers` and `packages/modules/*`
+  - shared lockfile: root `package-lock.json` (workspace installs update this single file)
+- For workspace-scoped dependency changes, prefer targeted commands to reduce lockfile churn:
+  - `npm install -w @testcontainers/<module>`
+  - `npm uninstall -w @testcontainers/<module> <package>`
+
+## Development Expectations
+
+- If a public API changes, update the relevant docs in the same PR.
+- If new types are made part of the public API, export them from the package's `index.ts` in the same PR.
+- If new learnings or misunderstandings are discovered, propose an `AGENTS.md` update in the same PR.
+- In docs Markdown, keep `<!--codeinclude-->` blocks tight with no blank lines between the markers and the include line, or the rendered snippet will contain blank lines between code lines.
+- Tests should verify observable behavior changes, not only internal/config state.
+  - Example: for a security option, assert a real secure/insecure behavior difference.
+- Test-only helper files under `src` (for example `*-test-utils.ts`) must be explicitly excluded from package `tsconfig.build.json` so they are not emitted into `build` and accidentally published.
+- Vitest runs tests concurrently by default (`sequence.concurrent: true` in `vitest.config.ts`).
+  - Tests that rely on shared/global mocks (for example `vi.spyOn` on shared loggers/singletons) can be flaky due to interleaving or automatic mock resets.
+  - Prefer asserting observable behavior instead of shared global mock state when possible.
+  - If a test must depend on shared/global mock state, use `it.sequential(...)` or `describe.sequential(...)`.
+
+## Permission and Escalation
+
+- `npm install` requires escalated permissions for outbound network access to npm registries.
+- `npm test` commands should be run with escalation so tests can access the Docker socket.
+
+### Escalation hygiene
+
+- Use specific commands and clear justifications.
+- Prefer narrow reruns rather than broad full-suite reruns when iterating.
+
+## PR Process
+
+1. Start from `main`.
+2. Create a branch prefixed with `codex/`.
+3. Implement scoped changes only.
+4. Run required checks: `npm run format`, `npm run lint`, and targeted tests.
+5. Verify git diff only contains intended files.
+6. Never commit, push, or post on GitHub (issues, PRs, or comments) without first sharing the proposed diff/message and getting explicit user approval.
+7. Commit with focused message(s), using `git commit --no-verify`.
+   - Never bypass signing (for example, do not use `--no-gpg-sign`).
+   - If signing fails (for example, passphrase/key issues), stop and ask the user to resolve signing, then retry.
+8. Push branch. Ask for explicit user permission before any force push.
+9. Open PR against `main` using a human-readable title (no `feat(...)` / `fix(...)` prefixes, and no agent-identifying prefixes or suffixes).
+   - Default to a ready-for-review PR. Only open or keep a PR in draft when the user explicitly asks for a draft.
+   - When using `gh` to create/edit PR descriptions, prefer `--body-file <path>` over inline `--body`; this avoids shell command substitution issues when the body contains backticks.
+10. Add labels for both change type and semantic version impact.
+11. Ensure PR body includes:
+    - summary of changes
+    - verification commands run
+    - test results summary
+    - if semver impact is not `major`, evidence that the change is not breaking
+    - `Closes #<issue>` only when the PR is intended to close a specific issue
+
+## Labels
+
+### Change type
+
+- `enhancement`
+- `bug`
+- `dependencies`
+- `documentation`
+- `maintenance`
+
+### Semver impact
+
+- `major`
+- `minor`
+- `patch`
+
+### Common mappings
+
+- backward-compatible feature: `enhancement` + `minor`
+- backward-compatible bug fix: `bug` + `patch`
+- breaking change: type label + `major`
+- docs-only change: `documentation` + usually `patch`
+- dependency update: `dependencies` + impact label based on user-facing effect
+
+## Lockfile Hygiene
+
+- Recheck `package-lock.json` after `npm install` for unrelated drift and revert unrelated changes.

CONTRIBUTING.md

@@ -31,7 +31,7 @@ Then access the docs at [http://localhost:8000](http://localhost:8000).
 
 #### Using Python
 
-* Ensure that you have Python 3.8.0 or higher.
+* Ensure that you have Python 3.11.0 or higher.
 * Set up a virtualenv and run `pip install -r requirements.txt` in the `testcontainers-node` root directory.
 * Once Python dependencies have been installed, run `mkdocs serve` to start a local auto-updating MkDocs server.
 

docs/features/compose.md

@@ -29,22 +29,25 @@ Provide a list of service names to only start those services:
 
 ```js
 const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
-  .up(["redis-1", "postgres-1"]);
+  .up(["redis", "postgres"]);
 ```
 
 ### With wait strategy
 
+`withWaitStrategy` expects **container names**, not service names. With Docker Compose v2, the default container name for the first replica is usually `<service>-1`.
+
 ```js
 const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
   .withWaitStrategy("redis-1", Wait.forLogMessage("Ready to accept connections"))
   .withWaitStrategy("postgres-1", Wait.forHealthCheck())
-  .up();
+  .up(["redis", "postgres"]);
 ```
 
 ### With a default wait strategy
 
-By default Testcontainers uses the "listening ports" wait strategy for all containers. If you'd like to override
-the default wait strategy for all services, you can do so:
+By default, Testcontainers waits for a service health check when one is defined in the Compose service or image. If no health check is defined, or the service disables health checks, it waits for listening ports.
+
+If you'd like to override the default wait strategy for all services, you can do so:
 
 ```js
 const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
@@ -142,6 +145,19 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
   .up();
 ```
 
+### With auto cleanup disabled
+
+By default Testcontainers registers the compose project with Ryuk so the stack is torn down automatically when the process exits. You can disable that registration for a specific compose stack:
+
+```js
+const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
+  .withProjectName("test")
+  .withAutoCleanup(false)
+  .up();
+```
+
+This only disables automatic cleanup. Explicit calls to `.down()`, `.stop()`, or `await using` disposal still tear the stack down as usual.
+
 ### With custom client options
 
 See [docker-compose](https://github.com/PDMLab/docker-compose/) library.
@@ -187,7 +203,7 @@ await environment.stop();
 
 ## Interacting with the containers
 
-Interact with the containers in your compose environment as you would any other Generic Container. Note that the container name suffix has changed from `_` to `-` between docker-compose v1 and v2 respectively.
+Interact with the containers in your compose environment as you would any other Generic Container. Compose-managed container names use the `<service-name>-<index>` format.
 
 ```js
 const container = environment.getContainer("alpine-1");

docs/features/containers.md

@@ -137,6 +137,9 @@ const container = await new GenericContainer("alpine")
     tar: nodeReadable,
     target: "/some/nested/remotedir"
   }])
+  .withCopyToContainerOptions({
+    copyUIDGID: true
+  })
   .start();
 ```
 
@@ -157,9 +160,13 @@ container.copyContentToContainer([{
   content: "hello world",
   target: "/remote/file2.txt"
 }])
-container.copyArchiveToContainer(nodeReadable, "/some/nested/remotedir");
+container.copyArchiveToContainer(nodeReadable, "/some/nested/remotedir", {
+  copyUIDGID: true
+});
 ```
 
+When copying files, symbolic links in `source` are followed and the linked file content is copied into the container.
+
 An optional `mode` can be specified in octal for setting file permissions:
 
 ```js
@@ -182,6 +189,21 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
+Archive copy options can also be specified:
+
+```js
+const container = await new GenericContainer("alpine")
+  .withCopyToContainerOptions({
+    copyUIDGID: true,
+    noOverwriteDirNonDir: true
+  })
+  .start();
+```
+
+- `copyUIDGID`: preserve UID/GID from tar archive entries.
+  Note: Podman may ignore this for archive copy in some cases, see [containers/podman#27538](https://github.com/containers/podman/issues/27538).
+- `noOverwriteDirNonDir`: fail if extraction would replace a file with a directory (or vice versa).
+
 ### Copy archive from container
 
 Files and directories can be fetched from a started or stopped container as a tar archive. The archive is returned as a readable stream:
@@ -245,6 +267,16 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
+### With security options
+
+See [Security options](https://docs.docker.com/engine/reference/run/#security-configuration).
+
+```js
+const container = await new GenericContainer("alpine")
+  .withSecurityOpt("no-new-privileges")
+  .start();
+```
+
 ### With added capabilities
 
 See [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html).
@@ -368,6 +400,16 @@ const container = await new GenericContainer("alpine")
 await container.stop({ remove: true }); // The container is stopped *AND* removed
 ```
 
+You can also disable automatic Ryuk cleanup for a specific container while leaving it enabled for the rest of the test session:
+
+```js
+const container = await new GenericContainer("alpine")
+  .withAutoCleanup(false)
+  .start();
+```
+
+This only affects automatic cleanup when the process exits unexpectedly or the container is otherwise left running. Explicit calls to `.stop()` still use the normal stop and removal behavior, so combine this with `.withAutoRemove(false)` or `.stop({ remove: false })` if you also want explicit stops to keep the container.
+
 Keep in mind that disabling ryuk (set `TESTCONTAINERS_RYUK_DISABLED` to `true`) **and** disabling automatic removal of containers will make containers persist after you're done working with them.
 
 

docs/features/wait-strategies.md

@@ -10,9 +10,15 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
+## Default wait strategy
+
+By default, Testcontainers waits for a container health check when one is defined by the image or configured with `withHealthCheck`. If no health check is defined, or the image disables health checks with `HEALTHCHECK NONE`, it waits up to 60 seconds for mapped network ports to be bound.
+
+You can override this selection with `withWaitStrategy`.
+
 ## Listening ports
 
-The default wait strategy used by Testcontainers. It will wait up to 60 seconds for the container's mapped network ports to be bound.
+Wait up to 60 seconds for the container's mapped network ports to be bound.
 
 ```js
 const { GenericContainer } = require("testcontainers");
@@ -75,10 +81,10 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
-Define your own health check. Note that time units are in seconds:
+Define your own health check. Testcontainers uses this as the default wait strategy unless you explicitly set another wait strategy. Note that time units are in milliseconds:
 
 ```js
-const { GenericContainer, Wait } = require("testcontainers");
+const { GenericContainer } = require("testcontainers");
 
 const container = await new GenericContainer("alpine")
   .withHealthCheck({
@@ -88,7 +94,6 @@ const container = await new GenericContainer("alpine")
     retries: 5,
     startPeriod: 1000,
   })
-  .withWaitStrategy(Wait.forHealthCheck())
   .start();
 ```
 

docs/modules/azurite.md

@@ -59,3 +59,17 @@ Choose an image from the [container registry](https://hub.docker.com/r/microsoft
 <!--codeinclude-->
 [](../../packages/modules/azurite/src/azurite-container.test.ts) inside_block:customPorts
 <!--/codeinclude-->
+
+### With HTTPS (PEM certificate)
+
+<!--codeinclude-->
+[Code](../../packages/modules/azurite/src/azurite-container.test.ts) inside_block:httpsWithPem
+[`azurite-test-utils`](../../packages/modules/azurite/src/azurite-test-utils.ts) inside_block:azuriteTestUtils
+<!--/codeinclude-->
+
+### With OAuth (basic)
+
+<!--codeinclude-->
+[Code](../../packages/modules/azurite/src/azurite-container.test.ts) inside_block:withOAuth
+[`azurite-test-utils`](../../packages/modules/azurite/src/azurite-test-utils.ts) inside_block:azuriteTestUtils
+<!--/codeinclude-->

docs/modules/localstack.md

@@ -16,9 +16,27 @@ These examples use the following libraries:
 
 Choose an image from the [container registry](https://hub.docker.com/r/localstack/localstack) and substitute `IMAGE`.
 
+!!! note "Authentication requirements"
+    Starting on March 23, 2026, LocalStack moved to authenticated image releases. Older pinned tags may continue to work without `LOCALSTACK_AUTH_TOKEN`, but newer releases require it.
+
+    Prefer pinning a specific image tag instead of using `latest`. If the image tag you use requires authentication, pass `LOCALSTACK_AUTH_TOKEN` when starting the container:
+
+    ```typescript
+    const token = process.env.LOCALSTACK_AUTH_TOKEN;
+
+    if (!token) {
+      throw new Error("LOCALSTACK_AUTH_TOKEN must be set for authenticated LocalStack images");
+    }
+
+    const container = await new LocalstackContainer("localstack/localstack:IMAGE")
+      .withEnvironment({ LOCALSTACK_AUTH_TOKEN: token })
+      .start();
+    ```
+
+    Refer to the [LocalStack announcement](https://blog.localstack.cloud/localstack-single-image-next-steps/) for the current rollout details.
+
 ### Create a S3 bucket
 
 <!--codeinclude-->
 [](../../packages/modules/localstack/src/localstack-container.test.ts) inside_block:localstackCreateS3Bucket
 <!--/codeinclude-->
-