integration

Documentation

Overview

Package integration contains testcontainers-driven integration tests.

Each test package starts exactly one VictoriaMetrics container in SetupSuite, shares it across all tests, and tears it down on completion. Series are injected via VM's /api/v1/import/prometheus endpoint with absolute timestamps so time-bucket alignment is deterministic.

These tests require Docker on the host. They are skipped when the `DOCKER_HOST` environment variable is unset and Docker isn't reachable — see vmsuite.go.

Index

• Constants
• func SkipIfDockerUnavailable(t *testing.T)
• func StampLabels(exposition, extra string) string
• type APIOption
  • func WithClock(clk clock.Clock) APIOption
  • func WithRouteResolver(rr build.RouteResolver, perCallTimeout time.Duration) APIOption
• type VMSuite
  • func (s *VMSuite) ForceFlush()
  • func (s *VMSuite) IngestExpFmt(exposition string)
  • func (s *VMSuite) SetupSuite()
  • func (s *VMSuite) StartAPIServer(configure func(*config.Config), opts ...APIOption) *httptest.Server
  • func (s *VMSuite) TearDownSuite()
  • func (s *VMSuite) VMURL() string
  • func (s *VMSuite) WaitForReady(budget time.Duration)
  • func (s *VMSuite) WaitForSeries(query string, evalTime time.Time, budget time.Duration) bool

Constants

const VMImage = "victoriametrics/victoria-metrics:v1.107.0"

VMImage is the pinned VictoriaMetrics container image used across the integration suite. Pinned by tag — never `:latest` — per D20.

Functions

func SkipIfDockerUnavailable

func SkipIfDockerUnavailable(t *testing.T)

SkipIfDockerUnavailable short-circuits the suite when Docker isn't usable. Used by `go test ./...` runs on developer machines without Docker so the rest of the test tree still runs.

func StampLabels

func StampLabels(exposition, extra string) string

StampLabels injects extra label pairs into every series line of an exposition block, skipping any key the line already carries. It models the scrape-time external labels a real deployment adds (`az`, `env`, `cluster`), so a fixture written for topology shape does not have to repeat them on every line — and a test that wants a DIFFERENT value (or none) simply spells that key out itself.

Types

type APIOption

type APIOption func(*apiOptions)

APIOption tweaks the in-process API server constructed by StartAPIServer. Functional options keep production New() signatures stable while letting tests inject deterministic substitutes (e.g. a fixed clock).

func WithClock

func WithClock(clk clock.Clock) APIOption

WithClock pins the server's Clock dependency. nil falls back to clock.System.

func WithRouteResolver

func WithRouteResolver(rr build.RouteResolver, perCallTimeout time.Duration) APIOption

WithRouteResolver injects an Istio route-resolution engine into the in-process server's build pipeline (translate-global-fqdn-to-k8s-service). Mirrors how cmd/kube-state-graph wires pkg/route when --route-store-dsn is set; nil (the default) keeps the feature off.

type VMSuite

type VMSuite struct {
	suite.Suite

	// HTTPAuthUsername / HTTPAuthPassword, when both non-empty, start the
	// container with `-httpAuth.username` / `-httpAuth.password` so every VM
	// endpoint except the exempt `/health` requires basic auth. Embedding
	// suites set them BEFORE calling VMSuite.SetupSuite. The suite's own
	// helpers (readiness, ingest, series polling) authenticate automatically.
	HTTPAuthUsername string
	HTTPAuthPassword string

	// ExtraLabels is stamped onto every series ingested through IngestExpFmt
	// that does not already carry the key — the scrape-time external labels a
	// real deployment applies. Set it in SetupSuite/SetupTest; leave empty for
	// suites whose fixtures spell every label out.
	ExtraLabels string
	// contains filtered or unexported fields
}

VMSuite is the base suite type embedded by every integration suite that needs a real VictoriaMetrics backend. It starts one container per suite, exposes helpers for series ingestion + readiness, and tears the container down at the end.

func (*VMSuite) ForceFlush

func (s *VMSuite) ForceFlush()

ForceFlush makes everything ingested so far immediately queryable.

This is the single reason the suites are not dominated by waiting. VictoriaMetrics registers a brand-NEW series into the searchable index on a periodic tick, so a fixture's first sample is invisible for ~10s (measured on the pinned image: 10.59s for a fresh label set, versus 0.017s for a new sample on a series that already exists). Every test seeds its own label sets, so every test paid it. /internal/force_flush is VM's test-oriented endpoint for exactly this and collapses the wait to ~30ms.

A non-2xx is NOT fatal: the endpoint is an internal convenience, and the WaitForSeries polls that follow every ingest remain the actual correctness gate — losing the flush costs latency, never a wrong result.

func (*VMSuite) IngestExpFmt

func (s *VMSuite) IngestExpFmt(exposition string)

IngestExpFmt POSTs Prometheus exposition-format text to VM's /api/v1/import/prometheus endpoint. Each line is one sample. When ExtraLabels is set it is stamped onto every series first (see StampLabels).

func (*VMSuite) SetupSuite

func (s *VMSuite) SetupSuite()

SetupSuite starts the VictoriaMetrics container and waits for readiness.

func (*VMSuite) StartAPIServer

func (s *VMSuite) StartAPIServer(configure func(*config.Config), opts ...APIOption) *httptest.Server

StartAPIServer constructs an in-process API server pointed at the running VictoriaMetrics container, wraps it in httptest.NewServer, and returns the server's base URL. Caller-supplied configure func may tweak the Config; optional APIOptions tweak Server-level dependencies.

func (*VMSuite) TearDownSuite

func (s *VMSuite) TearDownSuite()

TearDownSuite stops and removes the container.

func (*VMSuite) VMURL

func (s *VMSuite) VMURL() string

VMURL returns the base URL of the running VictoriaMetrics instance.

func (*VMSuite) WaitForReady

func (s *VMSuite) WaitForReady(budget time.Duration)

WaitForReady polls VM's `up{}` (effectively, /-/ready) until it answers or the budget is exhausted.

func (*VMSuite) WaitForSeries

func (s *VMSuite) WaitForSeries(query string, evalTime time.Time, budget time.Duration) bool

WaitForSeries polls VM until the supplied PromQL returns a non-empty vector at the given evaluation time or the budget is exhausted. evalTime is forwarded as the `time=` parameter; pass time.Time{} to evaluate at the server's current time. On budget exhaustion it logs the final probe URL and response so failures are debuggable from the test log.