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 configurations containing larger and more complex combinations of transforms.
Executing tests within a configuration file can be done with the test
subcommand:
vector test /etc/vector/*.toml
Configuration
- Common
- Advanced
[transforms.foo]type = "regex_parser"regex = "^(?P<timestamp>[\\w\\-:\\+]+) (?P<level>\\w+) (?P<message>.*)$"[[tests]]# Inputs[[tests.inputs]]insert_at = "foo" # requiredtype = "raw" # requiredvalue = "some message contents" # required, required when type = "raw"# Generalname = "foo test" # required# Outputs[[tests.outputs]]# Conditionsconditions.type = "check_fields" # optional, defaultconditions."message.eq" = "this is the content to match against" # exampleconditions."message.eq" = ["match this", "or this"] # exampleconditions."message.contains" = "foo" # exampleconditions."message.contains" = ["foo", "bar"] # exampleconditions."environment.ends_with" = "-staging" # exampleconditions."environment.ends_with" = ["-staging", "-running"] # exampleconditions."message.regex" = " (any|of|these|five|words) " # exampleconditions."environment.starts_with" = "staging-" # exampleconditions."environment.starts_with" = ["staging-", "running-"] # example# Generalextract_from = "foo" # required
For more information about unit tests check out this guide.
- required[table]
inputs
A table that defines a unit test input event.
- requiredstring
insert_at
The name of a transform, the input event will be delivered to this transform in order to begin the test.
- View examples
- required*table
log_fields
Specifies the log fields when the input type is 'log'.
- required*
[field-name]
A key/value pair representing a field to be added to the input event.
- View examples
- required*table
metric
Specifies the metric type when the input type is 'metric'.
- optionalstring
direction
The direction to increase or decrease the gauge value.
- Enum, must be one of:
"plus"
"minus"
- View examples
- Enum, must be one of:
- requiredstring
name
The name of the metric. Defaults to
<field>_total
forcounter
and<field>
forgauge
.- View examples
- optionalfloat
sample_rate
The bucket/distribution which contains the metric.
- View examples
- optionaltable
tags
Key/value pairs representing metric tags.
- requiredstring
[tag-name]
Key/value pairs representing metric tags.
- View examples
- requiredstring
timestamp
Time metric was created/ingested.
- View examples
- requiredstring
type
The metric type.
- Enum, must be one of:
"counter"
"gauge"
"histogram"
"set"
- View examples
- Enum, must be one of:
- requiredfloat
val
Amount to increment/decrement or gauge.
- View examples
- requiredstring
type
The event type.
- Enum, must be one of:
"raw"
"log"
"metric"
- View examples
- Enum, must be one of:
- required*string
value
Specifies the log message field contents when the input type is 'raw'.
- Only required when: type = "raw"
- View examples
- requiredstring
name
A unique identifier for this test.
- View examples
- required[string]
no_outputs_from
A list of transforms that must NOT output events in order for the test to pass.
- View examples
- required[table]
outputs
A table that defines a unit test expected output.
- optional[table]
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.
- optionalstring
type
The type of the condition to execute.
- Default:
"check_fields"
- Enum, must be one of:
"check_fields"
"is_log"
"is_metric"
- View examples
- Default:
- optionalstring
[field-name]
.eqCheck whether a field's contents exactly matches the value specified. This may be a single string or a list of strings, in which case this evaluates to true if any of the list matches.
- Only relevant when: type = "check_fields"
- View examples
- optionalbool
[field-name]
.existsCheck whether a field exists or does not exist, depending on the provided value being
true
orfalse
respectively.- Only relevant when: type = "check_fields"
- View examples
- optionalstring
[field-name]
.neqCheck whether a field's contents does not match the value specified. This may be a single string or a list of strings, in which case this evaluates to false if any of the list matches.
- Only relevant when: type = "check_fields"
- View examples
- optionalany
[field-name]
.not_[condition]
Check if the given
[condition]
does not match.- Only relevant when: type = "check_fields"
- View examples
- optionalstring
[field_name]
.containsChecks whether a string field contains a string argument. This may be a single string or a list of strings, in which case this evaluates to true if any of the list matches.
- Only relevant when: type = "check_fields"
- View examples
- optionalstring
[field_name]
.ends_withChecks whether a string field ends with a string argument. This may be a single string or a list of strings, in which case this evaluates to true if any of the list matches.
- Only relevant when: type = "check_fields"
- View examples
- optionalstring
[field_name]
.ip_cidr_containsChecks whether an IP field is contained within a given IP CIDR (works with IPv4 and IPv6). This may be a single string or a list of strings, in which case this evaluates to true if the IP field is contained within any of the CIDRs in the list.
- Only relevant when: type = "check_fields"
- View examples
- optionalstring
[field_name]
.regexChecks whether a string field matches a regular expression. Vector uses the documented Rust Regex syntax. Note that this condition is considerably more expensive than a regular string match (such as
starts_with
orcontains
) so the use of those conditions are preferred where possible.- Only relevant when: type = "check_fields"
- View examples
- optionalstring
[field_name]
.starts_withChecks whether a string field starts with a string argument. This may be a single string or a list of strings, in which case this evaluates to true if any of the list matches.
- Only relevant when: type = "check_fields"
- View examples
- requiredstring
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.
- View examples