blob: 399e604deb3681a3a74b439aa3e1cde5c7434d15 [file] [log] [blame]
// Copyright 2022 The Abseil Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// -----------------------------------------------------------------------------
// File: log/scoped_mock_log.h
// -----------------------------------------------------------------------------
//
// This header declares `class absl::ScopedMockLog`, for use in testing.
#ifndef ABSL_LOG_SCOPED_MOCK_LOG_H_
#define ABSL_LOG_SCOPED_MOCK_LOG_H_
#include <atomic>
#include <string>
#include "gmock/gmock.h"
#include "absl/base/config.h"
#include "absl/base/log_severity.h"
#include "absl/log/log_entry.h"
#include "absl/log/log_sink.h"
namespace absl {
ABSL_NAMESPACE_BEGIN
// MockLogDefault
//
// Controls how ScopedMockLog responds to unexpected calls by default.
enum class MockLogDefault { kIgnoreUnexpected, kDisallowUnexpected };
// ScopedMockLog
//
// ScopedMockLog is a LogSink that intercepts LOG() messages issued during its
// lifespan.
//
// Using this together with GoogleTest, it's easy to test how a piece of code
// calls LOG(). The typical usage, noting the distinction between
// "uninteresting" and "unexpected", looks like this:
//
// using ::testing::_;
// using ::testing::AnyNumber;
// using ::testing::EndsWith;
// using ::testing::kDoNotCaptureLogsYet;
// using ::testing::Lt;
//
// TEST(FooTest, LogsCorrectly) {
// // Simple robust setup, ignores unexpected logs.
// absl::ScopedMockLog log;
//
// // We expect the WARNING "Something bad!" exactly twice.
// EXPECT_CALL(log, Log(absl::LogSeverity::kWarning, _, "Something bad!"))
// .Times(2);
//
// // But we want no messages from foo.cc.
// EXPECT_CALL(log, Log(_, EndsWith("/foo.cc"), _)).Times(0);
//
// log.StartCapturingLogs(); // Call this after done setting expectations.
// Foo(); // Exercises the code under test.
// }
//
// TEST(BarTest, LogsExactlyCorrectly) {
// // Strict checking, fails for unexpected logs.
// absl::ScopedMockLog log(absl::MockLogDefault::kDisallowUnexpected);
//
// // ... but ignore low severity messages
// EXPECT_CALL(log, Log(Lt(absl::LogSeverity::kWarning), _, _))
// .Times(AnyNumber());
//
// // We expect the ERROR "Something bad!" exactly once.
// EXPECT_CALL(log, Log(absl::LogSeverity::kError, EndsWith("/foo.cc"),
// "Something bad!"))
// .Times(1);
//
// log.StartCapturingLogs(); // Call this after done setting expectations.
// Bar(); // Exercises the code under test.
// }
//
// Note that in a multi-threaded environment, all LOG() messages from a single
// thread will be handled in sequence, but that cannot be guaranteed for
// messages from different threads. In fact, if the same or multiple
// expectations are matched on two threads concurrently, their actions will be
// executed concurrently as well and may interleave.
class ScopedMockLog final {
public:
// ScopedMockLog::ScopedMockLog()
//
// Sets up the log and adds default expectations.
explicit ScopedMockLog(
MockLogDefault default_exp = MockLogDefault::kIgnoreUnexpected);
ScopedMockLog(const ScopedMockLog&) = delete;
ScopedMockLog& operator=(const ScopedMockLog&) = delete;
// ScopedMockLog::~ScopedMockLog()
//
// Stops intercepting logs and destroys this ScopedMockLog.
~ScopedMockLog();
// ScopedMockLog::StartCapturingLogs()
//
// Starts log capturing if the object isn't already doing so. Otherwise
// crashes.
//
// Usually this method is called in the same thread that created this
// ScopedMockLog. It is the user's responsibility to not call this method if
// another thread may be calling it or StopCapturingLogs() at the same time.
// It is undefined behavior to add expectations while capturing logs is
// enabled.
void StartCapturingLogs();
// ScopedMockLog::StopCapturingLogs()
//
// Stops log capturing if the object is capturing logs. Otherwise crashes.
//
// Usually this method is called in the same thread that created this object.
// It is the user's responsibility to not call this method if another thread
// may be calling it or StartCapturingLogs() at the same time.
//
// It is UB to add expectations, while capturing logs is enabled.
void StopCapturingLogs();
// ScopedMockLog::UseAsLocalSink()
//
// Each `ScopedMockLog` is implemented with an `absl::LogSink`; this method
// returns a reference to that sink (e.g. for use with
// `LOG(...).ToSinkOnly()`) and marks the `ScopedMockLog` as having been used
// even if `StartCapturingLogs` is never called.
absl::LogSink& UseAsLocalSink();
// Implements the mock method:
//
// void Log(LogSeverity severity, absl::string_view file_path,
// absl::string_view message);
//
// The second argument to Log() is the full path of the source file in
// which the LOG() was issued.
//
// This is a shorthand form, which should be used by most users. Use the
// `Send` mock only if you want to add expectations for other log message
// attributes.
MOCK_METHOD(void, Log,
(absl::LogSeverity severity, const std::string& file_path,
const std::string& message));
// Implements the mock method:
//
// void Send(const absl::LogEntry& entry);
//
// This is the most generic form of mock that can be specified. Use this mock
// only if you want to add expectations for log message attributes different
// from the log message text, log message path and log message severity.
//
// If no expectations are specified for this mock, the default action is to
// forward the call to the `Log` mock.
MOCK_METHOD(void, Send, (const absl::LogEntry&));
// Implements the mock method:
//
// void Flush();
//
// Use this mock only if you want to add expectations for log flush calls.
MOCK_METHOD(void, Flush, ());
private:
class ForwardingSink final : public absl::LogSink {
public:
explicit ForwardingSink(ScopedMockLog* sml) : sml_(sml) {}
ForwardingSink(const ForwardingSink&) = delete;
ForwardingSink& operator=(const ForwardingSink&) = delete;
void Send(const absl::LogEntry& entry) override { sml_->Send(entry); }
void Flush() override { sml_->Flush(); }
private:
ScopedMockLog* sml_;
};
ForwardingSink sink_;
bool is_capturing_logs_;
// Until C++20, the default constructor leaves the underlying value wrapped in
// std::atomic uninitialized, so all constructors should be sure to initialize
// is_triggered_.
std::atomic<bool> is_triggered_;
};
ABSL_NAMESPACE_END
} // namespace absl
#endif // ABSL_LOG_SCOPED_MOCK_LOG_H_