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

vector.toml
[transforms.foo]
type = "regex_parser"
regex = "^(?P<timestamp>[\\w\\-:\\+]+) (?P<level>\\w+) (?P<message>.*)$"
[[tests]]
# General
name = "foo test" # required
# Inputs
[[tests.inputs]]
insert_at = "foo" # required
type = "raw" # required
value = "some message contents" # required, required when type = "raw"
# Outputs
[[tests.outputs]]
# Conditions
conditions.type = "check_fields" # optional, default
conditions."message.eq" = "this is the content to match against" # example
conditions."message.contains" = "foo" # example
conditions."environment.ends_with" = "-staging" # example
conditions."message.regex" = " (any|of|these|five|words) " # example
conditions."environment.starts_with" = "staging-" # example
# General
extract_from = "foo" # required

For more information about unit tests check out this guide.

  • stringcommonrequired

    name

    A unique identifier for this test.

    • No default
    • View examples
  • [string]required

    no_outputs_from

    A list of transforms that must NOT output events in order for the test to pass.

    • No default
    • View examples
  • [table]commonrequired

    inputs

    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
    • stringenumcommonrequired

      type

      The event type.

      • No default
      • Enum, must be one of: "raw" "log" "metric"
      • View examples
    • stringcommonrequired*

      value

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

      • Only required when: type = "raw"
      • No default
      • View examples
    • tablerequired*

      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
    • tablerequired*

      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
      • 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
      • tablecommonoptional
        tags

        Key/value pairs representing metric tags.

        • stringcommonrequired
          [tag-name]

          Key/value pairs representing metric tags.

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

      • stringenumcommonoptional
        type

        The type of the condition to execute.

        • Default: "check_fields"
        • Enum, must be one of: "check_fields" "is_log" "is_metric"
        • View examples
      • stringcommonoptional
        [field-name].eq

        Check whether a fields contents exactly matches the value specified.

        • Only relevant when: type = "check_fields"
        • No default
        • View examples
      • booloptional
        [field-name].exists

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

        • Only relevant when: type = "check_fields"
        • No default
        • View examples
      • stringoptional
        [field-name].neq

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

        • Only relevant when: type = "check_fields"
        • No default
        • View examples
      • stringcommonoptional
        [field_name].contains

        Checks whether a string field contains a string argument.

        • Only relevant when: type = "check_fields"
        • No default
        • View examples
      • stringcommonoptional
        [field_name].ends_with

        Checks whether a string field ends with a string argument.

        • Only relevant when: type = "check_fields"
        • No default
        • View examples
      • stringcommonoptional
        [field_name].regex

        Checks 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 or contains) so the use of those conditions are preferred where possible.

        • Only relevant when: type = "check_fields"
        • No default
        • View examples
      • stringcommonoptional
        [field_name].starts_with

        Checks whether a string field starts with a string argument.

        • Only relevant when: type = "check_fields"
        • 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