1 // `promassert` is the easiest way to test prometheus metrics in go unit tests. 2 // It handles the hard parts so you can test metrics using one-line assert statements. 3 // 4 // `promassert` works by scraping the prometheus exposition format, in-memory, from promhttp.Handler(). 5 // Each member of the ParsedMetrics slice represents one line in the exposition format. 6 // Each line itself represents a unique collection label combinations, and their values. 7 // For example, you might see the following lines for the metric "http_requests_total": 8 // 9 // # HELP http_requests_total The total number of HTTP requests. 10 // # TYPE http_requests_total counter 11 // http_requests_total{method="post",code="200"} 42 12 // http_requests_total{method="post",code="204"} 777 13 // http_requests_total{method="get",code="404"} 8 14 // 15 // Parsing this metric would return a slice containing 3 members. 16 // 17 // pm := promassert.Counter("http_requests_total") // this scrapes and parses the metric 18 // 19 // That slice can be used as-is when testing across all the labels and values: 20 // 21 // pm.Exists(t) // true 22 // pm.Equals(t, 42.0 + 777.0 + 8.0) // true 23 // pm.LabelKeysExist(t, "method", "code") // true 24 // 25 // ParsedMetrics can be filtered based on labels: 26 // 27 // labels := map[string]string{"method":"post"} 28 // pm.With(labels).Exists(t) // true 29 // pm.With(labels).Equals(t, 42.0 + 777.0) // true 30 // labels["code"] = "204" 31 // pm.With(labels).Exists(t) // true 32 // pm.With(labels).Equals(t, 777.0) // true 33 // 34 // Sometimes you need to exit immediately when an assertion fails. 35 // Simply check the returned value and return: 36 // 37 // if !pm.Exists(t) { 38 // return 39 // } 40 // 41 // For more advanced testing, you can inspect the ParsedMetrics values directly. 42 // A good strategy when using the `go test --count=N` flag, is to get the value at the beginning of the test. 43 // Then do whatever increases the metric, and assert based on that value. 44 // 45 // value := pm.TryFold() 46 // callSomeHTTPRequests() 47 // // you must reparse the metric after it changes. 48 // promassert.Counter("http_requests_total").GreaterThan(t, value) 49 // 50 // When `promassert.Verbose` is true, the assert library logs assertions. 51 // 52 // Every assert statement can take a nil `testing.T` as an argument. 53 // This feature is used for sad path testing in the `promassert_test` package. 54 // Providing a nil `testing.T` value turns off logging since logging uses `t.Logf(...)` 55 // 56 // For questions or comments, please reach out to Mathew Reny on slack. 57 package promassert 58