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

common onlyrequired only

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