promtool test rules: Unit Test Alerting Rules
promtool test rules <testfile> evaluates rules against synthetic time series and asserts the expected recorded values and firing alerts.
Validation catches syntax errors, but only unit tests prove a rule actually fires when it should. promtool test rules runs assertions against sample data so alert logic is verified in CI.
What it does
promtool test rules loads a test file that lists the rule files under test, input series (input_series), and expected outcomes (alert_rule_test, promql_expr_test). It evaluates the rules over simulated time and fails if any assertion does not match.
Common usage
promtool test rules tests/alerts_test.yml
# a minimal test file
# rule_files: [alerts.yml]
# evaluation_interval: 1m
# tests:
# - input_series:
# - series: 'up{job="api"}'
# values: '1 1 0 0 0 0'
# alert_rule_test:
# - eval_time: 5m
# alertname: InstanceDown
# exp_alerts: [{}]Options
| Test field | What it does |
|---|---|
| rule_files | Rule files exercised by the test |
| input_series | Synthetic series and their values over time |
| alert_rule_test | Assert alerts firing at an eval_time |
| promql_expr_test | Assert a PromQL expression result |
| exp_alerts | Expected alert labels and annotations |
In CI
Pair promtool test rules with promtool check rules: check catches syntax, test catches logic. A failed assertion exits non-zero and fails the job, so a rule that stops firing after a refactor is caught in the PR.
Common errors in CI
"FAILED: alertname:\"InstanceDown\", time:5m, exp:..., got:[]" means the rule did not fire when expected, usually a wrong threshold or for: duration. "unable to load test file: yaml: ..." means the test YAML is malformed. "rule_files set ... not found" means the path to the rule file is wrong relative to the test file.