Unit Tests

It's possible to define unit tests within a Vector configuration file that cover a network of transforms within the topology. The intention of these tests is to improve the maintainability of configs containing larger and more complex combinations of transforms.

Executing tests within a config file can be done with the test subcommand:

vector test /etc/vector/*.toml

Configuration

  • Common
  • Advanced
vector.toml
[transforms.bar]
type = "regex_parser"
regex = "^(?P<timestamp>\w*) (?P<level>\\w*) (?P<message>.*)$"
[[tests]]
# REQUIRED - General
name = "foo test" # example
# REQUIRED - Outputs
[[tests.outputs]]
# REQUIRED - General
extract_from = "bar" # example
# REQUIRED - Conditions
[[tests.outputs.conditions]]
# REQUIRED
type = "check_fields" # example
# OPTIONAL
name = "message.eq"
value = "this is the content to match against" # example
name = "host.exists"
value = true # example
name = "method.neq"
value = "POST" # example
# REQUIRED - Input
[tests.input]
# REQUIRED
type = "raw" # example, enum
insert_at = "foo" # example
# OPTIONAL
value = "some message contents" # example, no default, relevant when type = "raw"

For more information about unit tests check out this guide.

Options

3 items
commontablerequired

input

A table that defines a unit test input event.

commonstringrequired

insert_at

The name of a transform, the input event will be delivered to this transform in order to begin the test.

No default
View examples
tableoptional

log_fields

Specifies the log fields when the input type is 'log'.

common*required
[field-name]

A key/value pair representing a field to be added to the input event.

No default
View examples
tableoptional

metric

Specifies the metric type when the input type is 'metric'.

stringenumoptional
direction

The direction to increase or decrease the gauge value.

No default
Enum, must be one of: "plus" "minus"
View examples
commonstringrequired
name

The name of the metric. Defaults to <field>_total for counter and <field> for gauge.

No default
View examples
floatoptional
sample_rate

The bucket/distribution the metric is a part of.

No default
View examples
commontableoptional
tags

Key/value pairs representing metric tags.

commonstringrequired
[tag-name]

Key/value pairs representing metric tags.

No default
View examples
commonstringrequired
timestamp

Time metric was created/ingested.

No default
View examples
commonstringenumrequired
type

The metric type.

No default
Enum, must be one of: "counter" "gauge" "histogram" "set"
View examples
commonfloatrequired
val

Amount to increment/decrement or gauge.

No default
View examples
commonstringenumrequired

type

The event type.

No default
Enum, must be one of: "raw" "log" "metric"
View examples
commonstringoptional

value

Specifies the log message field contents when the input type is 'raw'.

No default
Only relevant when: type = "raw"
View examples
commonstringrequired

name

A unique identifier for this test.

No default
View examples
common[table]required

outputs

A table that defines a unit test expected output.

common[table]required

conditions

A table that defines a collection of conditions to check against the output of a transform. A test is considered to have passed when each condition has resolved true for one or more events extracted from the target transform.

commonstringoptional
<field_name>.eq

Check whether a fields contents exactly matches the value specified.

No default
View examples
commonbooloptional
<field_name>.exists

Check whether a field exists or does not exist, depending on the provided valuebeing true or false respectively.

No default
View examples
commonstringoptional
<field_name>.neq

Check whether a fields contents does not match the value specified.

No default
View examples
commonstringrequired
type

The type of the condition to execute. Currently only the check_fields type is available.

No default
View examples
commonstringrequired

extract_from

The name of a transform, at the end of the test events extracted from this transform will be checked against a table of conditions.

No default
View examples