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.

• commonrequired[table]

  inputs

  A table that defines a unit test input event.

  • commonrequiredstring

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

    • commonrequired*

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

    • enumoptionalstring

      direction

      The direction to increase or decrease the gauge value.

      • Enum, must be one of: "plus" "minus"
      • View examples
    • commonrequiredstring

      name

      The name of the metric. Defaults to <field>_total for counter and <field> for gauge.

      • View examples
    • optionalfloat

      sample_rate

      The bucket/distribution which contains the metric.

      • View examples
    • commonoptionaltable

      tags

      Key/value pairs representing metric tags.

      • commonrequiredstring

        [tag-name]

        Key/value pairs representing metric tags.

        • View examples
    • commonrequiredstring

      timestamp

      Time metric was created/ingested.

      • View examples
    • enumcommonrequiredstring

      type

      The metric type.

      • Enum, must be one of: "counter" "gauge" "histogram" "set"
      • View examples
    • commonrequiredfloat

      val

      Amount to increment/decrement or gauge.

      • View examples
  • enumcommonrequiredstring

    type

    The event type.

    • Enum, must be one of: "raw" "log" "metric"
    • View examples
  • commonrequired*string

    value

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

    • Only required when: type = "raw"
    • View examples
• commonrequiredstring

  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
• commonrequired[table]

  outputs

  A table that defines a unit test expected output.

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

    • enumcommonoptionalstring

      type

      The type of the condition to execute.

      • Default: "check_fields"
      • Enum, must be one of: "check_fields" "is_log" "is_metric"
      • View examples
    • commonoptionalstring

      [field-name].eq

      Check 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].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"
      • View examples
    • optionalstring

      [field-name].neq

      Check 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
    • commonoptionalstring

      [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"
      • View examples
    • commonoptionalstring

      [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"
      • View examples
    • optionalstring

      [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"
      • View examples
    • commonoptionalstring

      [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"
      • View examples
    • commonoptionalstring

      [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"
      • View examples
  • commonrequiredstring

    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