testlogger.go

package logging

import (
	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
	"go.uber.org/zap/zaptest/observer"
)

// Record is a log record captured by TestLogger.
type Record struct {
	// Level is the logging level of the record.
	Level Level
	// Message is the record message.
	Message string
	// Logger is the name of the named logger, empty for the unnamed one.
	Logger string
	// Caller is the call site ("file.go:42"), empty if the caller is not detected.
	Caller string
	// Fields are the fields added with WithKey, WithKeys, WithError and context extractors.
	// Values are as zap stores them: integers are int64, unsigned integers uint64, floats float64,
	// strings and bools as is. An error is stored under "error" as its text.
	Fields map[string]any
}

// TestLogger is a Logger recording everything it logs into memory. It is meant for tests of the code
// which takes a Logger: pass it as a dependency and check Records. It does not touch the active backend
// of the package and writes nothing anywhere. It is safe for concurrent use.
//
// Fatal records the message and panics with it instead of exiting the process.
type TestLogger struct {
	Logger

	zl      *zapLogger // the same as Logger, to reach optional interfaces
	backend *Backend
	logs    *observer.ObservedLogs
}

// NewTestLogger returns a TestLogger recording records of all levels up from LevelTrace.
// Options work as in Init: WithLevel restricts the recorded levels, WithContextExtractors makes
// WithContext work, WithConfig brings CustomLevels. Output, format and endpoint settings are ignored.
func NewTestLogger(opts ...Option) *TestLogger {
	config := NewConfig()
	config.Level = LevelTrace
	config.Apply(opts...)

	core, logs := observer.New(zapTraceLevel)
	backend := &Backend{st: newState(config.clone(), core, zap.WithFatalHook(zapcore.WriteThenPanic))}

	logger := backend.newLogger()

	return &TestLogger{Logger: logger, zl: logger, backend: backend, logs: logs}
}

var (
	_ Panicer = (*TestLogger)(nil)
	_ Namer   = (*TestLogger)(nil)
)

// Panic records the message and panics with it, see Panicer.
func (tl *TestLogger) Panic(args ...interface{}) { tl.zl.Panic(args...) }

// Panicf records the formatted message and panics with it, see Panicer.
func (tl *TestLogger) Panicf(format string, args ...interface{}) {
	tl.zl.Panicf(format, args...)
}

// WithName returns a named child logger whose records are captured too, see Namer.
func (tl *TestLogger) WithName(name string) Logger { return tl.zl.WithName(name) }

// Backend returns the backend of the test logger. Use it to make named and context loggers
// whose records are captured too: tl.Backend().NewNamedLogger("db").
func (tl *TestLogger) Backend() *Backend {
	return tl.backend
}

// Records returns a copy of the records captured so far, oldest first.
func (tl *TestLogger) Records() []Record {
	return tl.Match(func(Record) bool { return true })
}

// ByLevel returns the records of the level.
func (tl *TestLogger) ByLevel(level Level) []Record {
	return tl.Match(func(rec Record) bool { return rec.Level == level })
}

// Match returns the records for which the function reports true.
func (tl *TestLogger) Match(match func(Record) bool) []Record {
	var res []Record

	for _, entry := range tl.logs.All() {
		rec := newRecord(entry)
		if match(rec) {
			res = append(res, rec)
		}
	}

	return res
}

// Reset forgets the captured records.
func (tl *TestLogger) Reset() {
	tl.logs.TakeAll()
}

func newRecord(entry observer.LoggedEntry) Record {
	rec := Record{
		Level:   fromZapLevel(entry.Level),
		Message: entry.Message,
		Logger:  entry.LoggerName,
		Fields:  entry.ContextMap(),
	}

	if entry.Caller.Defined {
		rec.Caller = entry.Caller.TrimmedPath()
	}

	return rec
}

// fromZapLevel is the reverse of the level mapping done by zapLogger.
func fromZapLevel(level zapcore.Level) Level {
	switch {
	case level < zapcore.DebugLevel:
		return LevelTrace
	case level == zapcore.DebugLevel:
		return LevelDebug
	case level == zapcore.InfoLevel:
		return LevelInfo
	case level == zapcore.WarnLevel:
		return LevelWarn
	case level == zapcore.ErrorLevel:
		return LevelError
	case level == zapcore.PanicLevel:
		return LevelPanic
	default:
		return LevelFatal
	}
}

// Cleaner is implemented by *testing.T, *testing.B and testing.TB.
type Cleaner interface {
	Cleanup(func())
}

// UseTestLogger makes a TestLogger and installs its backend as the active one, so loggers made with
// package functions (NewLogger, NewNamedLogger, Default and others) are captured too.
// The previous backend and configuration are restored when the test is done.
//
// NOTE: the active backend is global, so tests using UseTestLogger must not run in parallel.
// Loggers made before the call keep using the previous backend.
func UseTestLogger(t Cleaner, opts ...Option) *TestLogger {
	tl := NewTestLogger(opts...)

	mu.Lock()
	previous, previousConfig := usingBackend, useConfig
	usingBackend, useConfig = tl.backend, &tl.backend.st.config
	mu.Unlock()

	t.Cleanup(func() {
		mu.Lock()
		usingBackend, useConfig = previous, previousConfig
		mu.Unlock()
	})

	return tl
}