Testing

Trivy has a large test suite that mixes plain unit tests, golden-file integration tests, and Wasm/Docker-bound end-to-end tests. This page describes how each kind is organized and how to run it.

Layout

Test kind	Where	How to run
Unit tests	Co-located *_test.go files	go test ./...
Integration tests	integration/ (*_test.go with build tag integration)	go test -tags=integration ./integration/...
Module tests	pkg/module/ and integration/module_test.go	go test -tags=module_test ./...
VM integration	integration/vm_test.go	go test -tags=vm_integration ./integration/...
Doc tests	docs/ flag-table generation	run via mage docs
Helm tests	helm/trivy/	.github/workflows/publish-chart.yaml runs them

The root go test ./... invocation runs only unit tests; integration and module tests are tagged so they do not slow down everyday iteration.

Unit tests

Most packages have a *_test.go file with table-driven tests. The pkg/iac/, pkg/fanal/, pkg/sbom/, and pkg/dependency/parser/ packages have especially large test fixtures because they parse and serialize many file formats.

Common helpers live in internal/testutil/ (test utilities), internal/cachetest/ (cache fakes), internal/dbtest/ (Trivy DB fakes), internal/gittest/ (git repository fixtures), internal/hooktest/, and internal/registrytest/ (a registry harness).

Golden files

Many output-shape tests use golden files. The convention is testdata/<scenario>.json.golden (or .txt.golden, .sarif.golden). To regenerate after an intentional change:

go test ./pkg/report/... -update

Most test packages support an -update flag wired through flag.BoolVar(&update, "update", false, ...). Check the test file before assuming the flag exists.

Integration tests

integration/ contains end-to-end tests that build the binary and exercise it against real container images, registries, Git repositories, and Kubernetes clusters. They are gated by the integration build tag and assume a workable Docker daemon and network access.

Key files:

• integration/integration_test.go — shared helpers and the bulk of the standalone tests.
• integration/client_server_test.go — runs trivy server and trivy client end-to-end.
• integration/docker_engine_test.go — exercises the Docker engine artifact handler.
• integration/registry_test.go — uses a local OCI registry container.
• integration/k8s_test.go — kind-based Kubernetes cluster tests.
• integration/sbom_test.go — round-trips CycloneDX and SPDX SBOMs.
• integration/vm_test.go — VM image tests (build tag vm_integration).
• integration/module_test.go — exercises the WebAssembly module loader (build tag module_test).
• integration/repo_test.go — repository scans using internal/gittest/.

To run a focused scenario locally:

go test -tags=integration -run TestImage ./integration/

Test images are listed in integration/testimages.ini and pulled by the cache-test-assets.yaml workflow into a CI cache so PR runs do not hit Docker Hub rate limits.

Module tests

The WebAssembly module system has its own test directory under pkg/module/testdata/ with sample modules and a host loader test (pkg/module/module_test.go). Use:

go test -tags=module_test ./...

Test conventions

• Use testify's require for assertions that should stop the test on failure (require.NoError), and assert for soft assertions.
• Use cmpopts.SortSlices and cmpopts.IgnoreFields from github.com/google/go-cmp/cmp for ordering- and time-insensitive diffs.
• Time-sensitive code uses pkg/clock, which can be swapped to a fixed clock in tests via clock.With(ctx, t).
• Filesystem fakes use github.com/spf13/afero; image fakes use internal/registrytest/.

CI matrix

.github/workflows/test.yaml runs:

1. Lint — golangci-lint run on every PR.
2. Unit — go test ./... on Linux (and a smaller subset on macOS).
3. Integration — go test -tags=integration ./integration/... on Linux only.
4. Module — go test -tags=module_test ./....
5. Build — go build ./... to catch compile-only regressions.

Test asset caching is handled by .github/workflows/cache-test-assets.yaml.

Coverage

The repo does not publish coverage to a third-party service today, but you can compute it locally:

go test -coverprofile=cover.out ./...
go tool cover -html=cover.out -o cover.html