histogram_tester.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  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. #ifndef BASE_TEST_METRICS_HISTOGRAM_TESTER_H_
  5. #define BASE_TEST_METRICS_HISTOGRAM_TESTER_H_
  6. #include <functional>
  7. #include <map>
  8. #include <memory>
  9. #include <ostream>
  10. #include <string>
  11. #include <type_traits>
  12. #include <utility>
  13. #include <vector>
  14. #include "base/metrics/histogram.h"
  15. #include "base/metrics/histogram_base.h"
  16. #include "base/strings/string_piece.h"
  17. #include "base/time/time.h"
  18. #include "testing/gmock/include/gmock/gmock.h"
  19. namespace base {
  20. struct Bucket;
  21. class HistogramSamples;
  22. // HistogramTester provides a simple interface for examining histograms, UMA
  23. // or otherwise. Tests can use this interface to verify that histogram data is
  24. // getting logged as intended.
  25. //
  26. // Note: When using this class from a browser test, one might have to call
  27. // SubprocessMetricsProvider::MergeHistogramDeltasForTesting() to sync the
  28. // histogram data between the renderer and browser processes. If it is in a
  29. // content browser test, then content::FetchHistogramsFromChildProcesses()
  30. // should be used to achieve that.
  31. // To test histograms in Java tests, use HistogramTestRule.
  32. class HistogramTester {
  33. public:
  34. using CountsMap = std::map<std::string, HistogramBase::Count, std::less<>>;
  35. // Takes a snapshot of all current histograms counts.
  36. HistogramTester();
  37. HistogramTester(const HistogramTester&) = delete;
  38. HistogramTester& operator=(const HistogramTester&) = delete;
  39. ~HistogramTester();
  40. // We know the exact number of samples in a bucket, and that no other bucket
  41. // should have samples. Measures the diff from the snapshot taken when this
  42. // object was constructed.
  43. void ExpectUniqueSample(StringPiece name,
  44. HistogramBase::Sample sample,
  45. HistogramBase::Count expected_bucket_count) const;
  46. template <typename T>
  47. void ExpectUniqueSample(StringPiece name,
  48. T sample,
  49. HistogramBase::Count expected_bucket_count) const {
  50. ExpectUniqueSample(name, static_cast<HistogramBase::Sample>(sample),
  51. expected_bucket_count);
  52. }
  53. void ExpectUniqueTimeSample(StringPiece name,
  54. TimeDelta sample,
  55. HistogramBase::Count expected_bucket_count) const;
  56. // We know the exact number of samples in a bucket, but other buckets may
  57. // have samples as well. Measures the diff from the snapshot taken when this
  58. // object was constructed.
  59. void ExpectBucketCount(StringPiece name,
  60. HistogramBase::Sample sample,
  61. HistogramBase::Count expected_count) const;
  62. template <typename T>
  63. void ExpectBucketCount(StringPiece name,
  64. T sample,
  65. HistogramBase::Count expected_count) const {
  66. ExpectBucketCount(name, static_cast<HistogramBase::Sample>(sample),
  67. expected_count);
  68. }
  69. // We don't know the values of the samples, but we know how many there are.
  70. // This measures the diff from the snapshot taken when this object was
  71. // constructed.
  72. void ExpectTotalCount(StringPiece name, HistogramBase::Count count) const;
  73. // We know exact number of samples for buckets corresponding to a time
  74. // interval. Other intervals may have samples too.
  75. void ExpectTimeBucketCount(StringPiece name,
  76. TimeDelta sample,
  77. HistogramBase::Count count) const;
  78. // We don't know the values of the samples, but we know their sum.
  79. // This returns the diff from the snapshot taken when this object was
  80. // constructed.
  81. int64_t GetTotalSum(StringPiece name) const;
  82. // Returns a list of all of the buckets recorded since creation of this
  83. // object, as vector<Bucket>, where the Bucket represents the min boundary of
  84. // the bucket and the count of samples recorded to that bucket since creation.
  85. //
  86. // Example usage, using gMock:
  87. // EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"),
  88. // ElementsAre(Bucket(1, 5), Bucket(2, 10), Bucket(3, 5)));
  89. //
  90. // If you want make empty bucket explicit, use the BucketsAre() matcher
  91. // defined below:
  92. // EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"),
  93. // BucketsAre(Bucket(1, 0), Bucket(2, 10), Bucket(3, 5)));
  94. //
  95. // If you want to test a superset relation, prefer BucketsInclude() over
  96. // IsSupersetOf() because the former handles empty buckets as expected:
  97. // EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"),
  98. // BucketsInclude(Bucket(1, 0), Bucket(2, 10), Bucket(3, 5)));
  99. // With IsSupersetOf(), this expectation would always fail because
  100. // GetAllSamples() does not contain empty buckets.
  101. //
  102. // If you build the expected list programmatically, you can use the matchers
  103. // ElementsAreArray(), BucketsAreArray(), BucketsIncludeArray().
  104. //
  105. // If you prefer not to depend on gMock at the expense of a slightly less
  106. // helpful failure message, use EXPECT_EQ:
  107. // EXPECT_EQ(expected_buckets,
  108. // histogram_tester.GetAllSamples("HistogramName"));
  109. std::vector<Bucket> GetAllSamples(StringPiece name) const;
  110. // Returns the value of the |sample| bucket for ths histogram |name|.
  111. HistogramBase::Count GetBucketCount(StringPiece name,
  112. HistogramBase::Sample sample) const;
  113. template <typename T>
  114. HistogramBase::Count GetBucketCount(StringPiece name, T sample) const {
  115. return GetBucketCount(name, static_cast<HistogramBase::Sample>(sample));
  116. }
  117. // Finds histograms whose names start with |prefix|, and returns them along
  118. // with the counts of any samples added since the creation of this object.
  119. // Histograms that are unchanged are omitted from the result. The return value
  120. // is a map whose keys are the histogram name, and whose values are the sample
  121. // count.
  122. //
  123. // This is useful for cases where the code under test is choosing among a
  124. // family of related histograms and incrementing one of them. Typically you
  125. // should pass the result of this function directly to EXPECT_THAT.
  126. //
  127. // Example usage, using gmock (which produces better failure messages):
  128. // #include "testing/gmock/include/gmock/gmock.h"
  129. // ...
  130. // base::HistogramTester::CountsMap expected_counts;
  131. // expected_counts["MyMetric.A"] = 1;
  132. // expected_counts["MyMetric.B"] = 1;
  133. // EXPECT_THAT(histogram_tester.GetTotalCountsForPrefix("MyMetric."),
  134. // testing::ContainerEq(expected_counts));
  135. CountsMap GetTotalCountsForPrefix(StringPiece prefix) const;
  136. // Access a modified HistogramSamples containing only what has been logged
  137. // to the histogram since the creation of this object.
  138. std::unique_ptr<HistogramSamples> GetHistogramSamplesSinceCreation(
  139. StringPiece histogram_name) const;
  140. // Dumps all histograms that have had new samples added to them into a string,
  141. // for debugging purposes. Note: this will dump the entire contents of any
  142. // modified histograms and not just the modified buckets.
  143. std::string GetAllHistogramsRecorded() const;
  144. private:
  145. // Verifies and asserts that value in the |sample| bucket matches the
  146. // |expected_count|. The bucket's current value is determined from |samples|
  147. // and is modified based on the snapshot stored for histogram |name|.
  148. void CheckBucketCount(StringPiece name,
  149. HistogramBase::Sample sample,
  150. Histogram::Count expected_count,
  151. const HistogramSamples& samples) const;
  152. // Returns the total number of values recorded for histogram |name|. This
  153. // is calculated as the number from |samples| minus the snapshot that was
  154. // taken for |name|.
  155. int GetTotalCountForSamples(StringPiece name,
  156. const HistogramSamples& samples) const;
  157. // Verifies that the total number of values recorded for the histogram |name|
  158. // is |expected_count|. This is checked against |samples| minus the snapshot
  159. // that was taken for |name|.
  160. void CheckTotalCount(StringPiece name,
  161. Histogram::Count expected_count,
  162. const HistogramSamples& samples) const;
  163. // Sets the value for |count| to be the value in the |sample| bucket. The
  164. // bucket's current value is determined from |samples| and is modified based
  165. // on the snapshot stored for histogram |name|.
  166. void GetBucketCountForSamples(StringPiece name,
  167. HistogramBase::Sample sample,
  168. const HistogramSamples& samples,
  169. HistogramBase::Count* count) const;
  170. // Used to determine the histogram changes made during this instance's
  171. // lifecycle.
  172. std::map<std::string, std::unique_ptr<HistogramSamples>, std::less<>>
  173. histograms_snapshot_;
  174. };
  175. struct Bucket {
  176. Bucket(HistogramBase::Sample min, HistogramBase::Count count)
  177. : min(min), count(count) {}
  178. // A variant of the above constructor that accepts an `EnumType` for the `min`
  179. // value. Typically, this `EnumType` is the C++ enum (class) that is
  180. // associated with the metric this bucket is referring to.
  181. //
  182. // The constructor forwards to the above non-templated constructor. Therefore,
  183. // `EnumType` must be implicitly convertible to `HistogramBase::Sample`.
  184. template <typename MetricEnum,
  185. typename = std::enable_if_t<std::is_enum_v<MetricEnum>>>
  186. Bucket(MetricEnum min, HistogramBase::Count count)
  187. : Bucket(static_cast<std::underlying_type_t<MetricEnum>>(min), count) {}
  188. bool operator==(const Bucket& other) const;
  189. HistogramBase::Sample min;
  190. HistogramBase::Count count;
  191. };
  192. void PrintTo(const Bucket& value, std::ostream* os);
  193. // The BucketsAre[Array]() and BucketsInclude[Array]() matchers are intended to
  194. // match GetAllSamples().
  195. //
  196. // Unlike the standard matchers UnorderedElementsAreArray() and IsSupersetOf(),
  197. // they explicitly support empty buckets (`Bucket::count == 0`). Empty buckets
  198. // need special handling because GetAllSamples() doesn't contain empty ones.
  199. // BucketsAre() and BucketsAreArray() match a container that contains exactly
  200. // the non-empty `buckets`.
  201. //
  202. // For example,
  203. // EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"),
  204. // BucketsAre(Bucket(Enum::A, 0),
  205. // Bucket(Enum::B, 1),
  206. // Bucket(Enum::C, 2)));
  207. // - matches the actual value `{Bucket(B, 1), Bucket(C, 2)}`;
  208. // - does not match `{Bucket(A, n), Bucket(B, 1), Bucket(C, 2)}` for any `n`
  209. // (including `n == 0`).
  210. template <typename BucketArray>
  211. auto BucketsAreArray(BucketArray buckets) {
  212. auto non_empty_buckets = buckets;
  213. EraseIf(non_empty_buckets, [](Bucket b) { return b.count == 0; });
  214. return ::testing::UnorderedElementsAreArray(non_empty_buckets);
  215. }
  216. template <typename... BucketTypes>
  217. auto BucketsAre(BucketTypes... buckets) {
  218. return BucketsAreArray(std::vector<Bucket>{buckets...});
  219. }
  220. // BucketsInclude() and BucketsIncludeArray() are empty-bucket-friendly
  221. // replacements of IsSupersetOf[Array](): they match a container that contains
  222. // all non-empty `buckets` and none of the empty `buckets`.
  223. //
  224. // For example,
  225. // EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"),
  226. // BucketsInclude(Bucket(Enum::A, 0),
  227. // Bucket(Enum::B, 1),
  228. // Bucket(Enum::C, 2)));
  229. // - matches `{Bucket(B, 1), Bucket(C, 2), Bucket(D, 3)}`;
  230. // - not match `{Bucket(A, n), Bucket(B, 1), Bucket(C, 2), Bucket(D, 3)}` for
  231. // any `n` (including `n == 0`).
  232. template <typename BucketArray>
  233. auto BucketsIncludeArray(const BucketArray& buckets) {
  234. // The `empty_buckets` have `count == 0`, so the `HistogramBase::Sample`
  235. // suffices.
  236. std::vector<HistogramBase::Sample> empty_buckets;
  237. std::vector<Bucket> non_empty_buckets;
  238. for (const Bucket& b : buckets) {
  239. if (b.count == 0) {
  240. empty_buckets.push_back(b.min);
  241. } else {
  242. non_empty_buckets.push_back(b);
  243. }
  244. }
  245. using ::testing::AllOf;
  246. using ::testing::AnyOfArray;
  247. using ::testing::Each;
  248. using ::testing::Field;
  249. using ::testing::IsSupersetOf;
  250. using ::testing::Not;
  251. return AllOf(
  252. IsSupersetOf(non_empty_buckets),
  253. Each(Field("Bucket::min", &Bucket::min, Not(AnyOfArray(empty_buckets)))));
  254. }
  255. template <typename... BucketTypes>
  256. auto BucketsInclude(BucketTypes... buckets) {
  257. return BucketsIncludeArray(std::vector<Bucket>{buckets...});
  258. }
  259. } // namespace base
  260. #endif // BASE_TEST_METRICS_HISTOGRAM_TESTER_H_