apptest

package
v1.43.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 26, 2025 License: Apache-2.0 Imports: 23 Imported by: 0

README

App Integration Tests

The apptest package contains the integration tests for the VictoriaLogs applications (such as victoria-logs, vlagent and vlogscli).

An integration test aims at verifying the behavior of an application as a whole, as apposed to a unit test that verifies the behavior of a building block of an application.

To achieve that an integration test starts an application in a separate process and then issues HTTP requests to it and verifies the responses, examines the metrics the app exposes and/or files it creates, etc.

Note that an object of testing may be not just a single app, but several apps working together. A good example is VictoriaLogs cluster. An integration test may reproduce an arbitrary cluster configuration and verify how the components work together as a system.

The package provides a collection of helpers to start applications and make queries to them:

  • app.go - contains the generic code for staring an application and should not be used by integration tests directly.
  • {vlsingle,vlagent,etc}.go - build on top of app.go and provide the code for staring a specific application.
  • client.go - provides helper functions for sending HTTP requests to applications.

The integration tests themselves reside in tests/*_test.go files. Apart from having the _test suffix, there are no strict rules of how to name a file, but the name should reflect the prevailing purpose of the tests located in that file. For example, sharding_test.go aims at testing data sharding.

Since integration tests start applications in a separate process, they require the application binary files to be built and put into the bin directory. The build rule used for running integration tests, make apptest, accounts for that, it builds all application binaries before running the tests. But if you want to run the tests without make, i.e. by executing go test ./app/apptest, you will need to build the binaries first (for example, by executing make all).

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AssertOptions 

type AssertOptions struct {
	Msg        string
	Got        func() any
	Want       any
	CmpOpts    []cmp.Option
	DoNotRetry bool
	Retries    int
	Period     time.Duration
	FailNow    bool
}

AssertOptions hold the assertion params, such as got and wanted values as well as the message that should be included into the assertion error message in case of failure.

In VictoriaMetrics (especially the cluster version) the inserted data does not become visible for querying right away. Therefore, the first comparisons may fail. AssertOptions allow to configure how many times the actual result must be retrieved and compared with the expected one and for long to wait between the retries. If these two params (`Retries` and `Period`) are not set, the default values will be used.

If it is known that the data is available, then the retry functionality can be disabled by setting the `DoNotRetry` field.

AssertOptions are used by the TestCase.Assert() method, and this method uses cmp.Diff() from go-cmp package for comparing got and wanted values. AssertOptions, therefore, allows to pass cmp.Options to cmp.Diff() via `CmpOpts` field.

Finally the `FailNow` field controls whether the assertion should fail using `testing.T.Errorf()` or `testing.T.Fatalf()`.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is used for interacting with the apps over the network.

func NewClient 

func NewClient() *Client

NewClient creates a new client.

func (*Client) CloseConnections 

func (c *Client) CloseConnections()

CloseConnections closes client connections.

func (*Client) Delete 

func (c *Client) Delete(t *testing.T, url string) (string, int)

Delete sends a HTTP DELETE request and returns the response body and status code to the caller.

func (*Client) Get 

func (c *Client) Get(t *testing.T, url string) (string, int)

Get sends a HTTP GET request, returns the response body and status code to the caller.

func (*Client) Post 

func (c *Client) Post(t *testing.T, url, contentType string, data []byte) (string, int)

Post sends a HTTP POST request, returns the response body and status code to the caller.

func (*Client) PostForm 

func (c *Client) PostForm(t *testing.T, url string, data url.Values) (string, int)

PostForm sends a HTTP POST request containing the POST-form data, returns the response body and status code to the caller.

func (*Client) Write 

func (c *Client) Write(t *testing.T, address string, data []string)

type FacetsOpts added in v1.43.1 

type FacetsOpts struct {
	Start             string
	End               string
	Limit             string
	MaxValuesPerField string
	MaxValueLen       string
	KeepConstFields   string
	ExtraFilters      []string
}

FacetsOpts contains params used for querying VictoriaLogs via /select/logsql/facets

See https://docs.victoriametrics.com/victorialogs/querying/#querying-facets

type IngestOpts added in v1.40.0 

type IngestOpts struct {
	MessageField string
	StreamFields string
	TimeField    string
}

IngestOpts contains various params used for VictoriaLogs ingesting data

type LogsQLQueryResponse 

type LogsQLQueryResponse struct {
	LogLines []string
}

LogsQLQueryResponse is an in-memory representation of the /select/logsql/query response.

func NewLogsQLQueryResponse 

func NewLogsQLQueryResponse(t *testing.T, s string) *LogsQLQueryResponse

NewLogsQLQueryResponse is a test helper function that creates a new instance of LogsQLQueryResponse by unmarshalling a json string.

type QueryOpts 

type QueryOpts struct {
	Timeout      string
	Start        string
	End          string
	Limit        string
	ExtraFilters []string
}

QueryOpts contains params used for querying VictoriaLogs via /select/logsq/query

See https://docs.victoriametrics.com/victorialogs/querying/#querying-logs

type ServesMetrics 

type ServesMetrics struct {
	// contains filtered or unexported fields
}

ServesMetrics is used to retrieve the app's metrics.

This type is expected to be embedded by the apps that serve metrics.

func (*ServesMetrics) GetIntMetric 

func (app *ServesMetrics) GetIntMetric(t *testing.T, metricName string) int

GetIntMetric retrieves the value of a metric served by an app at /metrics URL. The value is then converted to int.

func (*ServesMetrics) GetMetric 

func (app *ServesMetrics) GetMetric(t *testing.T, metricName string) float64

GetMetric retrieves the value of a metric served by an app at /metrics URL.

func (*ServesMetrics) GetMetricsByPrefix 

func (app *ServesMetrics) GetMetricsByPrefix(t *testing.T, prefix string) []float64

GetMetricsByPrefix retrieves the values of all metrics that start with given prefix.

type StatsQueryOpts added in v1.40.0 

type StatsQueryOpts struct {
	Timeout      string
	Time         string
	ExtraFilters []string
}

StatsQueryOpts contains params used for querying VictoriaLogs via /select/logsq/stats_query

See https://docs.victoriametrics.com/victorialogs/querying/#querying-log-stats

type StatsQueryRangeOpts added in v1.40.0 

type StatsQueryRangeOpts struct {
	Timeout      string
	Start        string
	End          string
	Step         string
	ExtraFilters []string
}

StatsQueryRangeOpts contains params used for querying VictoriaLogs via /select/logsq/stats_query_range

See https://docs.victoriametrics.com/victorialogs/querying/#querying-log-range-stats

type Stopper 

type Stopper interface {
	Stop()
}

Stopper is an interface of objects that needs to be stopped via Stop() call

type TestCase 

type TestCase struct {
	// contains filtered or unexported fields
}

TestCase holds the state and defines clean-up procedure common for all test cases.

func NewTestCase 

func NewTestCase(t *testing.T) *TestCase

NewTestCase creates a new test case.

func (*TestCase) Assert 

func (tc *TestCase) Assert(opts *AssertOptions)

Assert compares the actual result with the expected one possibly multiple times in order to account for the fact that the inserted data does not become available for querying right away (especially in cluster version of VictoriaMetrics).

func (*TestCase) Client 

func (tc *TestCase) Client() *Client

Client returns an instance of the client that can be used for interacting with the app(s) under test.

func (*TestCase) Dir 

func (tc *TestCase) Dir() string

Dir returns the directory name that should be used by as the -storageDataDir.

func (*TestCase) MustStartDefaultVlagent 

func (tc *TestCase) MustStartDefaultVlagent(remoteWriteURLs []string) *Vlagent

MustStartDefaultVlagent is a test helper function that starts an instance of vlagent with defaults suitable for most tests.

func (*TestCase) MustStartDefaultVlcluster added in v1.43.1 

func (tc *TestCase) MustStartDefaultVlcluster() *Vlcluster

MustStartVlcluster starts Vlcluster with default settings

func (*TestCase) MustStartDefaultVlsingle 

func (tc *TestCase) MustStartDefaultVlsingle() *Vlsingle

MustStartDefaultVlsingle is a test helper function that starts an instance of vlsingle with defaults suitable for most tests.

func (*TestCase) MustStartVlagent 

func (tc *TestCase) MustStartVlagent(instance string, remoteWriteURLs []string, flags []string) *Vlagent

MustStartVlagent is a test helper function that starts an instance of vlagent and fails the test if the app fails to start.

func (*TestCase) MustStartVlsingle 

func (tc *TestCase) MustStartVlsingle(instance string, flags []string) *Vlsingle

MustStartVlsingle is a test helper function that starts an instance of vlsingle and fails the test if the app fails to start.

func (*TestCase) Stop 

func (tc *TestCase) Stop()

Stop performs the test case clean up, such as closing all client connections and removing the -storageDataDir directory.

Note that the -storageDataDir is not removed in case of test case failure to allow for further manual debugging.

func (*TestCase) StopApp 

func (tc *TestCase) StopApp(instance string)

StopApp stops the app identified by the `instance` name and removes it from the collection of started apps.

func (*TestCase) T 

func (tc *TestCase) T() *testing.T

T returns the test state.

type Vlagent 

type Vlagent struct {
	*ServesMetrics
	// contains filtered or unexported fields
}

Vlagent holds the state of a vlagent app and provides vlagent-specific functions

func MustStartVlagent added in v1.43.1 

func MustStartVlagent(t *testing.T, instance string, remoteWriteURLs []string, flags []string, cli *Client) *Vlagent

MustStartVlagent starts an instance of vlagent with the given flags. It also sets the default flags and populates the app instance state with runtime values extracted from the application log (such as httpListenAddr)

func (*Vlagent) JSONLineWrite 

func (app *Vlagent) JSONLineWrite(t *testing.T, records []string, opts IngestOpts)

JSONLineWrite is a test helper function that inserts a collection of records in json line format by sending a HTTP POST request to /insert/jsonline vlagent endpoint.

See https://docs.victoriametrics.com/victorialogs/data-ingestion/#json-stream-api

func (Vlagent) Name 

func (app Vlagent) Name() string

Name returns the application instance name.

func (Vlagent) Stop 

func (app Vlagent) Stop()

Stop sends the app process a SIGINT signal and waits until it terminates gracefully.

func (Vlagent) String 

func (app Vlagent) String() string

String returns the string representation of the app state.

func (*Vlagent) WaitQueueEmptyAfter 

func (app *Vlagent) WaitQueueEmptyAfter(t *testing.T, cb func())

WaitQueueEmptyAfter checks that persistent queue is empty after execution of provided callback

type Vlcluster added in v1.43.1 

type Vlcluster struct {
	// contains filtered or unexported fields
}

Vlcluster holds the state of a VictoriaLogs cluster.

func MustStartVlcluster added in v1.43.1 

func MustStartVlcluster(t *testing.T, instance string, storageFlags []string, cli *Client) *Vlcluster

MustStartVlcluster starts VictoriaLogs cluster with the given storageFlags for storage nodes. It also sets the default flags and populates the app instance state with runtime values extracted from the application log (such as httpListenAddr).

Stop must be called on the returned Vlcluster when it is no longer needed.

func (*Vlcluster) Facets added in v1.43.1 

func (app *Vlcluster) Facets(t *testing.T, query string, opts FacetsOpts) string

Facets sends the given query to /select/logsql/facets and returns the response.

See https://docs.victoriametrics.com/victorialogs/querying/#querying-facets

func (*Vlcluster) ForceFlush added in v1.43.1 

func (app *Vlcluster) ForceFlush(t *testing.T)

ForceFlush is a test helper function that forces the flushing of inserted data, so it becomes available for searching immediately.

func (*Vlcluster) JSONLineWrite added in v1.43.1 

func (app *Vlcluster) JSONLineWrite(t *testing.T, records []string, opts IngestOpts)

JSONLineWrite is a test helper function that inserts a collection of records in json line format by sending a HTTP POST request to /insert/jsonline vlsingle endpoint.

See https://docs.victoriametrics.com/victorialogs/data-ingestion/#json-stream-api

func (*Vlcluster) LogsQLQuery added in v1.43.1 

func (app *Vlcluster) LogsQLQuery(t *testing.T, query string, opts QueryOpts) *LogsQLQueryResponse

LogsQLQuery is a test helper function that performs PromQL/MetricsQL range query by sending a HTTP POST request to /select/logsql/query endpoint.

See https://docs.victoriametrics.com/victorialogs/querying/#querying-logs

func (*Vlcluster) Stop added in v1.43.1 

func (app *Vlcluster) Stop()

Stop stops app.

func (*Vlcluster) String added in v1.43.1 

func (app *Vlcluster) String() string

String returns the string representation of the app state.

type Vlsingle 

type Vlsingle struct {
	// contains filtered or unexported fields
}

Vlsingle holds the state of single-node VictoriaLogs.

func MustStartVlsingle added in v1.43.1 

func MustStartVlsingle(t *testing.T, instance string, flags []string, cli *Client) *Vlsingle

MustStartVlsingle starts an instance of vlsingle with the given flags. It also sets the default flags and populates the app instance state with runtime values extracted from the application log (such as httpListenAddr).

Stop must be called when the returned Vlsingle is no longer needed.

func (*Vlsingle) ForceFlush 

func (app *Vlsingle) ForceFlush(t *testing.T)

ForceFlush is a test helper function that forces the flushing of inserted data, so it becomes available for searching immediately.

func (*Vlsingle) HTTPAddr 

func (app *Vlsingle) HTTPAddr() string

HTTPAddr returns the address at which the vmstorage process is listening for http connections.

func (*Vlsingle) JSONLineWrite 

func (app *Vlsingle) JSONLineWrite(t *testing.T, records []string, opts IngestOpts)

JSONLineWrite is a test helper function that inserts a collection of records in json line format by sending a HTTP POST request to /insert/jsonline vlsingle endpoint.

See https://docs.victoriametrics.com/victorialogs/data-ingestion/#json-stream-api

func (*Vlsingle) LogsQLQuery 

func (app *Vlsingle) LogsQLQuery(t *testing.T, query string, opts QueryOpts) *LogsQLQueryResponse

LogsQLQuery is a test helper function that performs PromQL/MetricsQL range query by sending a HTTP POST request to /select/logsql/query endpoint.

See https://docs.victoriametrics.com/victorialogs/querying/#querying-logs

func (*Vlsingle) NativeWrite 

func (app *Vlsingle) NativeWrite(t *testing.T, records []logstorage.InsertRow, opts QueryOpts)

NativeWrite is a test helper function that sends a collection of records to /insert/native API.

See https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/app/vlinsert/internalinsert/internalinsert.go

func (*Vlsingle) StatsQueryRangeRaw added in v1.35.0 

func (app *Vlsingle) StatsQueryRangeRaw(t *testing.T, query string, opts StatsQueryRangeOpts) (string, int)

StatsQueryRangeRaw is a test helper function that performs a POST to /select/logsql/stats_query_range and returns raw body and status code.

See https://docs.victoriametrics.com/victorialogs/querying/#querying-log-range-stats

func (*Vlsingle) StatsQueryRaw added in v1.35.0 

func (app *Vlsingle) StatsQueryRaw(t *testing.T, query string, opts StatsQueryOpts) (string, int)

StatsQueryRaw is a test helper function that performs a POST to /select/logsql/stats_query and returns raw body and status code.

See https://docs.victoriametrics.com/victorialogs/querying/#querying-log-stats

func (*Vlsingle) Stop 

func (app *Vlsingle) Stop()

Stop stops app.

func (*Vlsingle) String 

func (app *Vlsingle) String() string

String returns the string representation of the vlsingle app state.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.