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 = "foo" # example
# OPTIONAL - Conditions
[[tests.outputs.conditions]]
# REQUIRED
type = "check_fields" # example
# OPTIONAL
"message.eq" = "this is the content to match against"
"host.exists" = true
"method.neq" = "POST"
# REQUIRED - Input
[tests.input]
# REQUIRED - General
type = "raw" # example, enum
insert_at = "foo" # example
# OPTIONAL - General
value = "some message contents" # example, no default, relevant when type = "raw"
# OPTIONAL - Log fields
[tests.input.log_fields]
message = "some message contents" # example
host = "myhost" # example
# OPTIONAL - Metric
[tests.input.metric]
# REQUIRED - General
type = "counter" # example, enum
name = "duration_total" # example
timestamp = "2019-11-01T21:15:47.443232Z" # example
val = 10.2 # example
# OPTIONAL - General
direction = "plus" # example, no default, enum
sample_rate = 1 # example, no default
# OPTIONAL - Tags
[tests.input.metric.tags]
host = "foohost" # example
region = "us-east-1" # example

For more information about unit tests check out this guide.

Options

3 items
tablecommonrequired

input

A table that defines a unit test input event.

stringcommonrequired

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'.

*commonrequired
[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
stringcommonrequired
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
tablecommonoptional
tags

Key/value pairs representing metric tags.

stringcommonrequired
[tag-name]

Key/value pairs representing metric tags.

No default
View examples
stringcommonrequired
timestamp

Time metric was created/ingested.

No default
View examples
stringenumcommonrequired
type

The metric type.

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

Amount to increment/decrement or gauge.

No default
View examples
stringenumcommonrequired

type

The event type.

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

value

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

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

name

A unique identifier for this test.

No default
View examples
[table]commonrequired

outputs

A table that defines a unit test expected output.

[table]commonoptional

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.An expected output without conditions instead prints the input and output of a target without checking its values.

stringcommonoptional
<field_name>.eq

Check whether a fields contents exactly matches the value specified.

No default
View examples
boolcommonoptional
<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
stringcommonoptional
<field_name>.neq

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

No default
View examples
stringcommonrequired
type

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

No default
View examples
stringcommonrequired

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