Testing

Vault has 773 *_test.go files (~310k lines) and a parallel UI test suite. There are five test layers, each with its own conventions.

1. Unit tests (make test)

make test                        # whole repo, race-enabled, parallel
make test TEST=./vault           # one package
make test TEST=./vault TESTARGS='-run TestCore_Init'  # one test

make test requires Docker because many "unit" tests stand up real backends (Postgres, MySQL, Cassandra, …) in containers. The race detector is enabled by default.

Idiomatic patterns:

• In-memory cores: tests instantiate a vault.TestCluster from vault/testing.go (~71k lines of helpers). It returns 3 in-process cores, ready to read/write.
• Test factories: every backend has a Factory test helper. For the framework backend see sdk/framework/backend_test.go.
• Storage: sdk/physical/inmem provides an HA-capable in-memory backend used everywhere.

2. External tests (vault/external_tests/)

The vault/external_tests/ tree (35 sub-packages) holds tests that need the public API surface, often spinning up a TestCluster with multiple nodes. Use these for HA, replication, raft, plugin, OIDC, and similar end-to-end behaviors.

3. Acceptance tests (make testacc)

Acceptance tests touch real cloud or third-party services and may incur cost. They're opt-in:

make testacc TEST=./builtin/logical/aws TESTARGS='-run TestAccBackend'

The required env vars are documented in each backend's README; the test will fast-fail with a "missing X" message if they're not set.

4. Enos scenario tests (enos/)

Enos is HashiCorp's scenario testing harness. It launches real Vault clusters on AWS, applies workloads, and asserts behavior. Scenarios are in enos/enos.vars.hcl, modules under enos/modules/, and CI wiring in .github/workflows/test-run-enos-scenario-matrix.yml and enos-release-testing-oss.yml.

Enos tests are not run in normal PR CI; they run on the release pipeline and nightly cron. If a PR needs Enos verification, a maintainer triggers the workflow.

5. UI tests

cd ui
pnpm install
pnpm test                       # full ember-cli test run
pnpm test:filter --filter '...' # focused
pnpm lint
pnpm test:browserstack          # cross-browser (used in CI)

End-to-end UI tests use Playwright; config is in ui/playwright.config.ts. Mirage (ui/mirage/) provides API mocks for component tests.

Detecting deadlocks

Vault uses sasha-s/go-deadlock selectively. Files like vault/test_cluster_detect_deadlock.go and vault/test_cluster_do_not_detect_deadlock.go toggle it via build tags. To run with deadlock detection:

go test -tags=deadlock ./vault

If a lock is held longer than the configured threshold, you'll get a panic with both stacks.

Plugin testing

Plugins use sdk/helper/testcluster/ (and sdk/helper/testcluster/docker/ for containerized builds). The README.md has a worked example using docker.NewTestDockerCluster to launch a 3-node cluster from the latest released hashicorp/vault image.

Snapshot and storage tests

For schema migrations or storage shape changes, write tests that exercise vault/init.go's rekey paths and that round-trip data through the AES-GCM barrier (vault/barrier_aes_gcm.go). Many physical/<backend>/*_test.go files compare reads/writes against an in-memory reference.

Performance / benchmarks

Some packages carry go test -bench benchmarks. The relevant CI workflow is .github/workflows/benchmark-prevent-performance-degradations.yml.

What CI actually runs

Looking at .github/workflows/, on every PR the project runs:

• ci.yml — orchestration entry point.
• test-go.yml — Go unit tests, sliced into a matrix.
• test-ui.yml — UI lint, build, and ember tests.
• code-checker.yml — gofmt, copywrite, license headers.
• actionlint.yml, enos-lint.yml — workflow / Enos lints.
• oss.yml — OSS-only checks (verifies Enterprise files aren't in the OSS branch).