Unit Testing for Rules

    1. # This is a list of rule files to consider for testing. Globs are supported.
    2. rule_files:
    3.   [ - <file_name> ]
    5. # optional, default = 1m
    6. evaluation_interval: <duration>
    8. # The order in which group names are listed below will be the order of evaluation of
    9. # rule groups (at a given evaluation time). The order is guaranteed only for the groups mentioned below.
    10. # All the groups need not be mentioned below.
    11. group_eval_order:
    12.   [ - <group_name> ]
    14. # All the tests are listed here.
    15. tests:
    16.   [ - <test_group> ]
    1. # Series data
    2. interval: <duration>
    3. input_series:
    4.   [ - <series> ]
    6. # Unit tests for the above data.
    8. # Unit tests for alerting rules. We consider the alerting rules from the input file.
    9. alert_rule_test:
    10.   [ - <alert_test_case> ]
    12. # Unit tests for PromQL expressions.
    13.   [ - <promql_test_case> ]
    15. # External labels accessible to the alert template.
    16. external_labels:

    <series>

    1. # The time elapsed from time=0s when the alerts have to be checked.
    2. eval_time: <duration>
    4. # Name of the alert to be tested.
    5. alertname: <string>
    7. # List of expected alerts which are firing under the given alertname at
    8. # given evaluation time. If you want to test if an alerting rule should
    9. # not be firing, then you can mention the above fields and leave 'exp_alerts' empty.
    10. exp_alerts:
    11.   [ - <alert> ]

    <alert>

    1. # These are the expanded labels and annotations of the expected alert.
    2. # Note: labels also include the labels of the sample associated with the
    3. # alert (same as what you see in `/alerts`, without series `__name__` and `alertname`)
    4. exp_labels:
    5.   [ <labelname>: <string> ]
    6. exp_annotations:
    7.   [ <labelname>: <string> ]

    <sample>

    1. # Labels of the sample in usual series notation '<metric name>{<label name>=<label value>, ...}'
    2. # Examples:
    3. #      series_name{label1="value1", label2="value2"}
    4. #      go_goroutines{job="prometheus", instance="localhost:9090"}
    5. labels: <string>
    7. # The expected value of the PromQL expression.
    8. value: <number>

    Example

    1. # This is the main input for unit testing.
    2. # Only this file is passed as command line argument.
    4. rule_files:
    5.     - alerts.yml
    7. evaluation_interval: 1m
    8. tests:
    9.     # Test 1.
    10.     - interval: 1m
    11.       # Series data.
    12.       input_series:
    13.           - series: 'up{job="prometheus", instance="localhost:9090"}'
    14.             values: '0 0 0 0 0 0 0 0 0 0 0 0 0 0 0'
    15.           - series: 'up{job="node_exporter", instance="localhost:9100"}'
    16.             values: '1+0x6 0 0 0 0 0 0 0 0' # 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0
    17.           - series: 'go_goroutines{job="prometheus", instance="localhost:9090"}'
    18.             values: '10+10x2 30+20x5' # 10 20 30 30 50 70 90 110 130
    19.           - series: 'go_goroutines{job="node_exporter", instance="localhost:9100"}'
    20.             values: '10+10x7 10+30x4' # 10 20 30 40 50 60 70 80 10 40 70 100 130
    22.       # Unit test for alerting rules.
    23.       alert_rule_test:
    24.           # Unit test 1.
    25.           - eval_time: 10m
    26.             alertname: InstanceDown
    27.             exp_alerts:
    28.                 # Alert 1.
    29.                 - exp_labels:
    30.                       severity: page
    31.                       instance: localhost:9090
    32.                       job: prometheus
    33.                   exp_annotations:
    34.                       summary: "Instance localhost:9090 down"
    35.                       description: "localhost:9090 of job prometheus has been down for more than 5 minutes."
    36.       # Unit tests for promql expressions.
    37.       promql_expr_test:
    38.           # Unit test 1.
    39.           - expr: go_goroutines > 5
    40.             eval_time: 4m
    41.             exp_samples:
    42.                 # Sample 1.
    43.                 - labels: 'go_goroutines{job="prometheus",instance="localhost:9090"}'
    44.                   value: 50
    45.                 # Sample 2.
    46.                   value: 50