Skip to main content

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​

  1. Install WireMock's standalone JAR:

    npm install --save-dev wiremock
  2. Add a setup file:

    examples/no-docker/no-docker.setup.ts
    import { installNoDockerRuntime } from "@hellaweb3/wiremock-testcontainers-nodejs/no-docker";
    import { NO_DOCKER_OPTIONS } from "./no-docker";

    installNoDockerRuntime(NO_DOCKER_OPTIONS);

    Source: examples/no-docker/no-docker.setup.ts (lines 8–11)

  3. Load it only when WIREMOCK_NO_DOCKER is set:

    examples/vitest.config.ts
    const noDocker = isNoDockerRequested(); // WIREMOCK_NO_DOCKER is "1" or "true"

    Source: examples/vitest.config.ts (lines 16–16)

    examples/vitest.config.ts
    setupFiles: noDocker ? ["./no-docker/no-docker.setup.ts"] : [],

    Source: examples/vitest.config.ts (lines 41–41)

  4. Set the variable from a --no-docker flag – refused in CI/CD:

    examples/scripts/test-e2e.mjs
    function 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 shell

    if (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);
    });
    }

    Source: examples/scripts/test-e2e.mjs (lines 33–55)

Run:

npm test --no-docker # or: npm test -- --no-docker

Configure​

installNoDockerRuntime(options?) takes NoDockerOptions and returns an uninstaller:

examples/no-docker/no-docker.ts
/** 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)

OptionEnvironmentDefault
jarWIREMOCK_JARThe wiremock package's JAR
javaWIREMOCK_JAVA, JAVA_HOMEjava
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:

examples/no-docker/no-docker.ts
/**
* 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?) – whether NO_DOCKER_ENV ("WIREMOCK_NO_DOCKER") is 1 or true.
  • 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.
examples/no-docker/no-docker.test.ts
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)

examples/no-docker/no-docker.test.ts
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​

examples/no-docker/no-docker.e2e.test.ts
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 (slower stop()); later starts are about twice as fast. JAVA_OPTS from withEnvironment() override the JVM flags.