Vault Module¶

Vault by HashiCorp is a tool for securely accessing secrets such as API keys, passwords, or certificates. This module allows you to run and initialize a Vault container for integration tests.

Install¶

npm install @testcontainers/vault --save-dev

Examples¶

Start and perform read/write with node-vault:

it("should start Vault and allow reading/writing secrets", async () => {
  await using container = await new VaultContainer(IMAGE).withVaultToken(VAULT_TOKEN).start();

  const client = vault({
    apiVersion: "v1",
    endpoint: container.getAddress(),
    token: container.getRootToken(),
  });

  await client.write("secret/data/hello", {
    data: {
      message: "world",
      other: "vault",
    },
  });

  const result = await client.read("secret/data/hello");
  const data = result?.data?.data;

  expect(data.message).toBe("world");
  expect(data.other).toBe("vault");
});

Run Vault CLI init commands at startup:

it("should execute init commands using vault CLI", async () => {
  await using container = await new VaultContainer(IMAGE)
    .withVaultToken(VAULT_TOKEN)
    .withInitCommands("secrets enable transit", "write -f transit/keys/my-key")
    .start();

  const result = await container.exec(["vault", "read", "-format=json", "transit/keys/my-key"]);

  expect(result.exitCode).toBe(0);
  expect(result.output).toContain("my-key");
});

Why use Vault in integration tests?¶

With the growing adoption of Vault in modern infrastructure, testing components that depend on Vault for secret resolution or encryption can be complex. This module allows:

Starting a local Vault instance during test runs
Seeding secrets or enabling engines with Vault CLI
Validating app behavior with secured data access

Use this module to test Vault-backed workflows without the need for pre-provisioned Vault infrastructure.