Running without Docker
With Java 11+, serve every WiremockContainer from a local WireMock JVM. Tests stay unchanged.
:::warning Local development only
installNoDockerRuntime() throws in CI/CD and warns on every start. Results can differ from the
Docker image – run with Docker before merging.
:::
Set up
-
Install WireMock's standalone JAR:
npm install --save-dev wiremock -
Add a setup file:
examples/no-docker/no-docker.setup.tsimport { installNoDockerRuntime } from "@hellaweb3/wiremock-testcontainers-nodejs/no-docker";import { NO_DOCKER_OPTIONS } from "./no-docker";installNoDockerRuntime(NO_DOCKER_OPTIONS); -
Load it only when
WIREMOCK_NO_DOCKERis set:examples/vitest.config.tsconst noDocker = isNoDockerRequested(); // WIREMOCK_NO_DOCKER is "1" or "true"Source:
examples/vitest.config.ts (lines 16–16)examples/vitest.config.tssetupFiles: noDocker ? ["./no-docker/no-docker.setup.ts"] : [], -
Set the variable from a
--no-dockerflag – refused in CI/CD:examples/scripts/test-e2e.mjsfunction main() {const args = process.argv.slice(2);const noDocker = args.includes(FLAG) || ["", "false"].includes(process.env.npm_config_docker);const env = { ...process.env };delete env[NO_DOCKER_ENV]; // the flag is the only switch – never inherited from the shellif (noDocker) {const ci = detectCI(process.env);if (ci) {console.error(paint("1;31", `✖ ${FLAG} is not allowed in CI/CD (detected ${ci}=${process.env[ci]}). Run the E2E suite with Docker.`));process.exitCode = 1;return;}console.warn(paint("1;33", BANNER));env[NO_DOCKER_ENV] = "1";}const vitest = join(dirname(createRequire(import.meta.url).resolve("vitest/package.json")), "vitest.mjs");const vitestArgs = args.filter((arg) => arg !== FLAG && arg !== "--");spawn(process.execPath, [vitest, "run", ...vitestArgs], { stdio: "inherit", env }).on("exit", (code, signal) => {process.exitCode = code ?? (signal ? 1 : 0);});}
Run:
npm test --no-docker # or: npm test -- --no-docker
Configure
installNoDockerRuntime(options?) takes NoDockerOptions and returns an uninstaller:
/** Every option is optional; these suit a busy laptop. */
export const NO_DOCKER_OPTIONS: NoDockerOptions = {
startupTimeout: 90_000, // default 60 s – a cold JVM can be slow
// jar: "./wiremock-standalone-3.13.2.jar", // default: $WIREMOCK_JAR, else the `wiremock` package's
// java: "/opt/jdk-21/bin/java", // default: $WIREMOCK_JAVA, $JAVA_HOME/bin/java, else `java`
// cacheDir: false, // default: a class-data cache in the OS temp dir
};
Source: examples/no-docker/no-docker.ts (lines 13–19)
| Option | Environment | Default |
|---|---|---|
jar | WIREMOCK_JAR | The wiremock package's JAR |
java | WIREMOCK_JAVA, JAVA_HOME | java |
startupTimeout | – | 60_000 ms |
cacheDir – false disables | – | <os tmpdir>/wiremock-testcontainers |
log | – | process.emitWarning |
env | – | process.env |
Install only when requested – for runners without conditional setup files:
/**
* Installs the runtime only if `WIREMOCK_NO_DOCKER` asks for it – for test runners whose setup
* files cannot be conditional. Returns the uninstaller, if installed.
* @throws In CI/CD, or if no WireMock JAR is found.
*/
export function installNoDockerIfRequested(options: NoDockerOptions = NO_DOCKER_OPTIONS): (() => void) | undefined {
return isNoDockerRequested(options.env) ? installNoDockerRuntime(options) : undefined;
}
Source: examples/no-docker/no-docker.ts (lines 23–30)
Detect CI and the request
isNoDockerRequested(env?)– whetherNO_DOCKER_ENV("WIREMOCK_NO_DOCKER") is1ortrue.detectCI(env?)– the CI/CD variable set, if any:CI,GITHUB_ACTIONS,GITLAB_CI,CIRCLECI,BUILDKITE,JENKINS_URL,TF_BUILD,TEAMCITY_VERSION,BITBUCKET_BUILD_NUMBER,CODEBUILD_BUILD_ID,CONTINUOUS_INTEGRATION.
it("detectCI() names the CI/CD variable that is set", () => {
expect(detectCI({ GITHUB_ACTIONS: "true" })).toBe("GITHUB_ACTIONS");
expect(detectCI({ CI: "false" })).toBeUndefined(); // "", "0" and "false" do not count
expect(detectCI({})).toBeUndefined();
});
it("isNoDockerRequested() reads WIREMOCK_NO_DOCKER", () => {
expect(NO_DOCKER_ENV).toBe("WIREMOCK_NO_DOCKER");
expect(isNoDockerRequested({ [NO_DOCKER_ENV]: "1" })).toBe(true);
expect(isNoDockerRequested({ [NO_DOCKER_ENV]: "true" })).toBe(true);
expect(isNoDockerRequested({ [NO_DOCKER_ENV]: "yes" })).toBe(false);
});
Source: examples/no-docker/no-docker.test.ts (lines 17–28)
it("installNoDockerRuntime() refuses to run in CI/CD", () => {
expect(() => installNoDockerRuntime({ env: { CI: "true" } })).toThrow("--no-docker must not be used in CI/CD (detected CI=true)");
});
it("installNoDockerRuntime() needs a WireMock JAR", () => {
expect(() => installNoDockerRuntime({ env: {}, jar: "./missing.jar" })).toThrow('--no-docker: WireMock JAR "');
});
Source: examples/no-docker/no-docker.test.ts (lines 32–38)
What differs
it("listens on 127.0.0.1 and serves the same stubs", async () => {
expect(wiremock.getHost()).toBe("127.0.0.1");
expect((await fetch(wiremock.getUrl("/payments"))).status).toBe(200);
});
it("logs() returns the JVM's output", async () => {
expect(await text(await wiremock.logs())).toMatch(/port:\s+\d+/u);
});
it("container-only features throw", async () => {
await expect(wiremock.exec(["ls"])).rejects.toThrow("exec() is not supported with --no-docker");
});
Source: examples/no-docker/no-docker.e2e.test.ts (lines 25–36)
- WireMock listens on
127.0.0.1; extension JARs join its class path. logs()returns the JVM's output.exec(), networks and copying files after start throw.- Leftover JVMs are killed when the test process exits.
- The first run records a class-data archive in
cacheDir(slowerstop()); later starts are about twice as fast.JAVA_OPTSfromwithEnvironment()override the JVM flags.