mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 1 | // Copyright 2014 The Chromium Authors. All rights reserved. |
| 2 | // Use of this source code is governed by a BSD-style license that can be |
| 3 | // found in the LICENSE file. |
| 4 | |
| 5 | #ifndef BASE_TEST_HISTOGRAM_TESTER_H_ |
| 6 | #define BASE_TEST_HISTOGRAM_TESTER_H_ |
| 7 | |
| 8 | #include <map> |
dcheng | cc8e4d8 | 2016-04-05 06:25:51 +0900 | [diff] [blame] | 9 | #include <memory> |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 10 | #include <ostream> |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 11 | #include <string> |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 12 | #include <utility> |
| 13 | #include <vector> |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 14 | |
avi | f09d539 | 2015-12-24 12:28:02 +0900 | [diff] [blame] | 15 | #include "base/macros.h" |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 16 | #include "base/metrics/histogram.h" |
| 17 | #include "base/metrics/histogram_base.h" |
nikunjb | 7961de9 | 2016-11-15 07:06:25 +0900 | [diff] [blame] | 18 | #include "base/time/time.h" |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 19 | |
| 20 | namespace base { |
| 21 | |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 22 | struct Bucket; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 23 | class HistogramSamples; |
| 24 | |
| 25 | // HistogramTester provides a simple interface for examining histograms, UMA |
| 26 | // or otherwise. Tests can use this interface to verify that histogram data is |
| 27 | // getting logged as intended. |
| 28 | class HistogramTester { |
| 29 | public: |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 30 | using CountsMap = std::map<std::string, HistogramBase::Count>; |
nick | b1c693a | 2015-07-28 03:29:59 +0900 | [diff] [blame] | 31 | |
François Degros | 0dd05ce | 2018-01-08 11:53:34 +0900 | [diff] [blame^] | 32 | // Takes a snapshot of all current histograms counts. |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 33 | HistogramTester(); |
| 34 | ~HistogramTester(); |
| 35 | |
| 36 | // We know the exact number of samples in a bucket, and that no other bucket |
| 37 | // should have samples. Measures the diff from the snapshot taken when this |
| 38 | // object was constructed. |
| 39 | void ExpectUniqueSample(const std::string& name, |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 40 | HistogramBase::Sample sample, |
| 41 | HistogramBase::Count expected_count) const; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 42 | |
| 43 | // We know the exact number of samples in a bucket, but other buckets may |
| 44 | // have samples as well. Measures the diff from the snapshot taken when this |
| 45 | // object was constructed. |
| 46 | void ExpectBucketCount(const std::string& name, |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 47 | HistogramBase::Sample sample, |
| 48 | HistogramBase::Count expected_count) const; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 49 | |
| 50 | // We don't know the values of the samples, but we know how many there are. |
| 51 | // This measures the diff from the snapshot taken when this object was |
| 52 | // constructed. |
| 53 | void ExpectTotalCount(const std::string& name, |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 54 | HistogramBase::Count count) const; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 55 | |
nikunjb | 7961de9 | 2016-11-15 07:06:25 +0900 | [diff] [blame] | 56 | // We know exact number of samples for buckets corresponding to a time |
| 57 | // interval. Other intervals may have samples too. |
| 58 | void ExpectTimeBucketCount(const std::string& name, |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 59 | TimeDelta sample, |
| 60 | HistogramBase::Count count) const; |
nikunjb | 7961de9 | 2016-11-15 07:06:25 +0900 | [diff] [blame] | 61 | |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 62 | // Returns a list of all of the buckets recorded since creation of this |
| 63 | // object, as vector<Bucket>, where the Bucket represents the min boundary of |
| 64 | // the bucket and the count of samples recorded to that bucket since creation. |
| 65 | // |
| 66 | // Example usage, using gMock: |
| 67 | // EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"), |
| 68 | // ElementsAre(Bucket(1, 5), Bucket(2, 10), Bucket(3, 5))); |
| 69 | // |
| 70 | // If you build the expected list programmatically, you can use ContainerEq: |
| 71 | // EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"), |
| 72 | // ContainerEq(expected_buckets)); |
| 73 | // |
| 74 | // or EXPECT_EQ if you prefer not to depend on gMock, at the expense of a |
| 75 | // slightly less helpful failure message: |
| 76 | // EXPECT_EQ(expected_buckets, |
| 77 | // histogram_tester.GetAllSamples("HistogramName")); |
nick | b1c693a | 2015-07-28 03:29:59 +0900 | [diff] [blame] | 78 | std::vector<Bucket> GetAllSamples(const std::string& name) const; |
| 79 | |
lunalu | 1f21075 | 2017-05-20 13:25:28 +0900 | [diff] [blame] | 80 | // Returns the value of the |sample| bucket for ths histogram |name|. |
| 81 | HistogramBase::Count GetBucketCount(const std::string& name, |
| 82 | HistogramBase::Sample sample) const; |
| 83 | |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 84 | // Finds histograms whose names start with |prefix|, and returns them along |
nick | b1c693a | 2015-07-28 03:29:59 +0900 | [diff] [blame] | 85 | // with the counts of any samples added since the creation of this object. |
| 86 | // Histograms that are unchanged are omitted from the result. The return value |
| 87 | // is a map whose keys are the histogram name, and whose values are the sample |
| 88 | // count. |
| 89 | // |
| 90 | // This is useful for cases where the code under test is choosing among a |
| 91 | // family of related histograms and incrementing one of them. Typically you |
| 92 | // should pass the result of this function directly to EXPECT_THAT. |
| 93 | // |
| 94 | // Example usage, using gmock (which produces better failure messages): |
| 95 | // #include "testing/gmock/include/gmock/gmock.h" |
| 96 | // ... |
| 97 | // base::HistogramTester::CountsMap expected_counts; |
| 98 | // expected_counts["MyMetric.A"] = 1; |
| 99 | // expected_counts["MyMetric.B"] = 1; |
| 100 | // EXPECT_THAT(histogram_tester.GetTotalCountsForPrefix("MyMetric."), |
| 101 | // testing::ContainerEq(expected_counts)); |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 102 | CountsMap GetTotalCountsForPrefix(const std::string& prefix) const; |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 103 | |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 104 | // Access a modified HistogramSamples containing only what has been logged |
| 105 | // to the histogram since the creation of this object. |
dcheng | cc8e4d8 | 2016-04-05 06:25:51 +0900 | [diff] [blame] | 106 | std::unique_ptr<HistogramSamples> GetHistogramSamplesSinceCreation( |
nick | b1c693a | 2015-07-28 03:29:59 +0900 | [diff] [blame] | 107 | const std::string& histogram_name) const; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 108 | |
| 109 | private: |
| 110 | // Verifies and asserts that value in the |sample| bucket matches the |
| 111 | // |expected_count|. The bucket's current value is determined from |samples| |
| 112 | // and is modified based on the snapshot stored for histogram |name|. |
| 113 | void CheckBucketCount(const std::string& name, |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 114 | HistogramBase::Sample sample, |
| 115 | Histogram::Count expected_count, |
| 116 | const HistogramSamples& samples) const; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 117 | |
| 118 | // Verifies that the total number of values recorded for the histogram |name| |
| 119 | // is |expected_count|. This is checked against |samples| minus the snapshot |
| 120 | // that was taken for |name|. |
| 121 | void CheckTotalCount(const std::string& name, |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 122 | Histogram::Count expected_count, |
| 123 | const HistogramSamples& samples) const; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 124 | |
lunalu | 1f21075 | 2017-05-20 13:25:28 +0900 | [diff] [blame] | 125 | // Sets the value for |count| to be the value in the |sample| bucket. The |
| 126 | // bucket's current value is determined from |samples| and is modified based |
| 127 | // on the snapshot stored for histogram |name|. |
| 128 | void GetBucketCountForSamples(const std::string& name, |
| 129 | HistogramBase::Sample sample, |
| 130 | const HistogramSamples& samples, |
| 131 | HistogramBase::Count* count) const; |
| 132 | |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 133 | // Used to determine the histogram changes made during this instance's |
avi | ace57a8 | 2016-10-27 13:10:51 +0900 | [diff] [blame] | 134 | // lifecycle. |
| 135 | std::map<std::string, std::unique_ptr<HistogramSamples>> histograms_snapshot_; |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 136 | |
| 137 | DISALLOW_COPY_AND_ASSIGN(HistogramTester); |
| 138 | }; |
| 139 | |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 140 | struct Bucket { |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 141 | Bucket(HistogramBase::Sample min, HistogramBase::Count count) |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 142 | : min(min), count(count) {} |
| 143 | |
| 144 | bool operator==(const Bucket& other) const; |
| 145 | |
pkalinnikov | 5b63bda | 2017-01-14 03:30:38 +0900 | [diff] [blame] | 146 | HistogramBase::Sample min; |
| 147 | HistogramBase::Count count; |
twifkak | 120eb32 | 2015-07-01 04:13:21 +0900 | [diff] [blame] | 148 | }; |
| 149 | |
| 150 | void PrintTo(const Bucket& value, std::ostream* os); |
| 151 | |
mlerman@chromium.org | a798068 | 2014-08-22 07:00:38 +0900 | [diff] [blame] | 152 | } // namespace base |
| 153 | |
| 154 | #endif // BASE_TEST_HISTOGRAM_TESTER_H_ |