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

vector.toml

[transforms.foo]
  type = "regex_parser"
  regex = "^(?P<timestamp>[\\w\\-:\\+]+) (?P<level>\\w+) (?P<message>.*)$"

[[tests]]
  # Inputs
  [[tests.inputs]]
    insert_at = "foo" # required
    type = "raw" # required
    value = "some message contents" # required, required when type = "raw"

  # General
  name = "foo test" # required

  # Outputs
  [[tests.outputs]]
    # Conditions
    conditions.type = "check_fields" # optional, default
    conditions."message.eq" = "this is the content to match against" # example
    conditions."message.eq" = ["match this", "or this"] # example
    conditions."message.contains" = "foo" # example
    conditions."message.contains" = ["foo", "bar"] # example
    conditions."environment.ends_with" = "-staging" # example
    conditions."environment.ends_with" = ["-staging", "-running"] # example
    conditions."message.regex" = " (any|of|these|five|words) " # example
    conditions."environment.starts_with" = "staging-" # example
    conditions."environment.starts_with" = ["staging-", "running-"] # example

    # General
    extract_from = "foo" # required

For more information about unit tests check out this guide.

4 items

commonrequired

• [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
  • 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
    • 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
  • stringcommonrequired*

    value

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

    • Only required when: type = "raw"
    • No default
    • View examples
  • No default
• 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

  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. 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"
      • 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. 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"
      • No default
      • View examples
    • anyoptional

      [field-name].not_[condition]

      Check if the given [condition] does not match.

      • Only relevant when: type = "check_fields"
      • No default
      • View examples
    • stringcommonoptional

      [field_name].contains

      Checks 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"
      • No default
      • View examples
    • stringcommonoptional

      [field_name].ends_with

      Checks 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"
      • No default
      • View examples
    • stringoptional

      [field_name].ip_cidr_contains

      Checks 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"
      • 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. 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"
      • No default
      • View examples
    • No default
  • 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
  • No default