blob: 8019931e5a85e8b1188faf30f361263fe0189d94 [file] [log] [blame]
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef BASE_TEST_HISTOGRAM_TESTER_H_
#define BASE_TEST_HISTOGRAM_TESTER_H_
#include <map>
#include <memory>
#include <ostream>
#include <string>
#include <utility>
#include <vector>
#include "base/macros.h"
#include "base/metrics/histogram.h"
#include "base/metrics/histogram_base.h"
#include "base/time/time.h"
namespace base {
struct Bucket;
class HistogramSamples;
// HistogramTester provides a simple interface for examining histograms, UMA
// or otherwise. Tests can use this interface to verify that histogram data is
// getting logged as intended.
//
// Note: When using this class from a browser test, one might have to call
// SubprocessMetricsProvider::MergeHistogramDeltasForTesting() to sync the
// histogram data between the renderer and browser processes. If it is in a
// content browser test, then content::FetchHistogramsFromChildProcesses()
// should be used to achieve that.
class HistogramTester {
public:
using CountsMap = std::map<std::string, HistogramBase::Count>;
// Takes a snapshot of all current histograms counts.
HistogramTester();
~HistogramTester();
// We know the exact number of samples in a bucket, and that no other bucket
// should have samples. Measures the diff from the snapshot taken when this
// object was constructed.
void ExpectUniqueSample(const std::string& name,
HistogramBase::Sample sample,
HistogramBase::Count expected_count) const;
template <typename T>
void ExpectUniqueSample(const std::string& name,
T sample,
HistogramBase::Count expected_count) const {
ExpectUniqueSample(name, static_cast<HistogramBase::Sample>(sample),
expected_count);
}
// We know the exact number of samples in a bucket, but other buckets may
// have samples as well. Measures the diff from the snapshot taken when this
// object was constructed.
void ExpectBucketCount(const std::string& name,
HistogramBase::Sample sample,
HistogramBase::Count expected_count) const;
template <typename T>
void ExpectBucketCount(const std::string& name,
T sample,
HistogramBase::Count expected_count) const {
ExpectBucketCount(name, static_cast<HistogramBase::Sample>(sample),
expected_count);
}
// We don't know the values of the samples, but we know how many there are.
// This measures the diff from the snapshot taken when this object was
// constructed.
void ExpectTotalCount(const std::string& name,
HistogramBase::Count count) const;
// We know exact number of samples for buckets corresponding to a time
// interval. Other intervals may have samples too.
void ExpectTimeBucketCount(const std::string& name,
TimeDelta sample,
HistogramBase::Count count) const;
// Returns a list of all of the buckets recorded since creation of this
// object, as vector<Bucket>, where the Bucket represents the min boundary of
// the bucket and the count of samples recorded to that bucket since creation.
//
// Example usage, using gMock:
// EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"),
// ElementsAre(Bucket(1, 5), Bucket(2, 10), Bucket(3, 5)));
//
// If you build the expected list programmatically, you can use ContainerEq:
// EXPECT_THAT(histogram_tester.GetAllSamples("HistogramName"),
// ContainerEq(expected_buckets));
//
// or EXPECT_EQ if you prefer not to depend on gMock, at the expense of a
// slightly less helpful failure message:
// EXPECT_EQ(expected_buckets,
// histogram_tester.GetAllSamples("HistogramName"));
std::vector<Bucket> GetAllSamples(const std::string& name) const;
// Returns the value of the |sample| bucket for ths histogram |name|.
HistogramBase::Count GetBucketCount(const std::string& name,
HistogramBase::Sample sample) const;
// Finds histograms whose names start with |prefix|, and returns them along
// with the counts of any samples added since the creation of this object.
// Histograms that are unchanged are omitted from the result. The return value
// is a map whose keys are the histogram name, and whose values are the sample
// count.
//
// This is useful for cases where the code under test is choosing among a
// family of related histograms and incrementing one of them. Typically you
// should pass the result of this function directly to EXPECT_THAT.
//
// Example usage, using gmock (which produces better failure messages):
// #include "testing/gmock/include/gmock/gmock.h"
// ...
// base::HistogramTester::CountsMap expected_counts;
// expected_counts["MyMetric.A"] = 1;
// expected_counts["MyMetric.B"] = 1;
// EXPECT_THAT(histogram_tester.GetTotalCountsForPrefix("MyMetric."),
// testing::ContainerEq(expected_counts));
CountsMap GetTotalCountsForPrefix(const std::string& prefix) const;
// Access a modified HistogramSamples containing only what has been logged
// to the histogram since the creation of this object.
std::unique_ptr<HistogramSamples> GetHistogramSamplesSinceCreation(
const std::string& histogram_name) const;
private:
// Verifies and asserts that value in the |sample| bucket matches the
// |expected_count|. The bucket's current value is determined from |samples|
// and is modified based on the snapshot stored for histogram |name|.
void CheckBucketCount(const std::string& name,
HistogramBase::Sample sample,
Histogram::Count expected_count,
const HistogramSamples& samples) const;
// Verifies that the total number of values recorded for the histogram |name|
// is |expected_count|. This is checked against |samples| minus the snapshot
// that was taken for |name|.
void CheckTotalCount(const std::string& name,
Histogram::Count expected_count,
const HistogramSamples& samples) const;
// Sets the value for |count| to be the value in the |sample| bucket. The
// bucket's current value is determined from |samples| and is modified based
// on the snapshot stored for histogram |name|.
void GetBucketCountForSamples(const std::string& name,
HistogramBase::Sample sample,
const HistogramSamples& samples,
HistogramBase::Count* count) const;
// Used to determine the histogram changes made during this instance's
// lifecycle.
std::map<std::string, std::unique_ptr<HistogramSamples>> histograms_snapshot_;
DISALLOW_COPY_AND_ASSIGN(HistogramTester);
};
struct Bucket {
Bucket(HistogramBase::Sample min, HistogramBase::Count count)
: min(min), count(count) {}
bool operator==(const Bucket& other) const;
HistogramBase::Sample min;
HistogramBase::Count count;
};
void PrintTo(const Bucket& value, std::ostream* os);
} // namespace base
#endif // BASE_TEST_HISTOGRAM_TESTER_H_