Skip to content

Commit

Permalink
promote experimental code to stable
Browse files Browse the repository at this point in the history 
ktesting is heavily used in Kubernetes already for testing. The test package is
also used. The textlogger is not used that much yet because it was still
experimental (and thus no replacement for normal klog), but it's simple and
unlikely to need any breaking API changes.
  • Loading branch information
@pohly
pohly committed Oct 26, 2023
1 parent 6632ba5 commit 18cdd3a
Show file tree
Hide file tree
Showing 8 changed files with 0 additions and 212 deletions.
5 changes: 0 additions & 5 deletions ktesting/init/init.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,6 @@ limitations under the License.
// Package init registers the command line flags for k8s.io/klogr/testing in
// the flag.CommandLine. This is done during initialization, so merely
// importing it is enough.
//
// # Experimental
//
// Notice: This package is EXPERIMENTAL and may be changed or removed in a
// later release.
package init

import (
Expand Down
45 changes: 0 additions & 45 deletions ktesting/options.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,6 @@ import (
// bind command line flags to the instance before passing it to NewTestContext.
//
// Must be constructed with NewConfig.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type Config struct {
vstate *verbosity.VState
co configOptions
Expand All @@ -54,11 +49,6 @@ func (c *Config) VModule() flag.Value {
}

// ConfigOption implements functional parameters for NewConfig.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type ConfigOption func(co *configOptions)

type configOptions struct {
Expand All @@ -72,23 +62,13 @@ type configOptions struct {
// AnyToString overrides the default formatter for values that are not
// supported directly by klog. The default is `fmt.Sprintf("%+v")`.
// The formatter must not panic.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func AnyToString(anyToString func(value interface{}) string) ConfigOption {
return func(co *configOptions) {
co.anyToString = anyToString
}
}

// VerbosityFlagName overrides the default -testing.v for the verbosity level.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func VerbosityFlagName(name string) ConfigOption {
return func(co *configOptions) {
co.verbosityFlagName = name
Expand All @@ -97,11 +77,6 @@ func VerbosityFlagName(name string) ConfigOption {

// VModulFlagName overrides the default -testing.vmodule for the per-module
// verbosity levels.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func VModuleFlagName(name string) ConfigOption {
return func(co *configOptions) {
co.vmoduleFlagName = name
Expand All @@ -114,11 +89,6 @@ func VModuleFlagName(name string) ConfigOption {
// https://github.com/kubernetes/community/blob/9406b4352fe2d5810cb21cc3cb059ce5886de157/contributors/devel/sig-instrumentation/logging.md#logging-conventions),
// which is useful when debugging a failed test. `go test` only shows the log
// output for failed tests. To see all output, use `go test -v`.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func Verbosity(level int) ConfigOption {
return func(co *configOptions) {
co.verbosityDefault = level
Expand All @@ -129,11 +99,6 @@ func Verbosity(level int) ConfigOption {
// to being printed. Off by default. Unit tests that want to verify that
// log entries are emitted as expected can turn this on and then retrieve
// the captured log through the Underlier LogSink interface.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func BufferLogs(enabled bool) ConfigOption {
return func(co *configOptions) {
co.bufferLogs = enabled
Expand All @@ -142,11 +107,6 @@ func BufferLogs(enabled bool) ConfigOption {

// NewConfig returns a configuration with recommended defaults and optional
// modifications. Command line flags are not bound to any FlagSet yet.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func NewConfig(opts ...ConfigOption) *Config {
c := &Config{
co: configOptions{
Expand All @@ -165,11 +125,6 @@ func NewConfig(opts ...ConfigOption) *Config {
}

// AddFlags registers the command line flags that control the configuration.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func (c *Config) AddFlags(fs *flag.FlagSet) {
fs.Var(c.vstate.V(), c.co.verbosityFlagName, "number for the log level verbosity of the testing logger")
fs.Var(c.vstate.VModule(), c.co.vmoduleFlagName, "comma-separated list of pattern=N log level settings for files matching the patterns")
Expand Down
10 changes: 0 additions & 10 deletions ktesting/setup.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,22 +24,12 @@ import (

// DefaultConfig is the global default logging configuration for a unit
// test. It is used by NewTestContext and k8s.io/klogr/testing/init.
//
// # Experimental
//
// Notice: This variable is EXPERIMENTAL and may be changed or removed in a
// later release.
var DefaultConfig = NewConfig()

// NewTestContext returns a logger and context for use in a unit test case or
// benchmark. The tl parameter can be a testing.T or testing.B pointer that
// will receive all log output. Importing k8s.io/klogr/testing/init will add
// command line flags that modify the configuration of that log output.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func NewTestContext(tl TL) (logr.Logger, context.Context) {
logger := NewLogger(tl, DefaultConfig)
ctx := logr.NewContext(context.Background(), logger)
Expand Down
65 changes: 0 additions & 65 deletions ktesting/testinglogger.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,6 @@ limitations under the License.
//
// Serialization of the structured log parameters is done in the same way
// as for klog.InfoS.
//
// # Experimental
//
// Notice: This package is EXPERIMENTAL and may be changed or removed in a
// later release.
package ktesting

import (
Expand All @@ -58,23 +53,13 @@ import (
)

// TL is the relevant subset of testing.TB.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type TL interface {
Helper()
Log(args ...interface{})
}

// NopTL implements TL with empty stubs. It can be used when only capturing
// output in memory is relevant.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type NopTL struct{}

func (n NopTL) Helper() {}
Expand All @@ -83,11 +68,6 @@ func (n NopTL) Log(args ...interface{}) {}
var _ TL = NopTL{}

// BufferTL implements TL with an in-memory buffer.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type BufferTL struct {
strings.Builder
}
Expand All @@ -109,11 +89,6 @@ var _ TL = &BufferTL{}
//
// Verbosity can be modified at any time through the Config.V and
// Config.VModule API.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
func NewLogger(t TL, c *Config) logr.Logger {
l := tlogger{
shared: &tloggerShared{
Expand Down Expand Up @@ -141,11 +116,6 @@ func NewLogger(t TL, c *Config) logr.Logger {

// Buffer stores log entries as formatted text and structured data.
// It is safe to use this concurrently.
//
// # Experimental
//
// Notice: This interface is EXPERIMENTAL and may be changed or removed in a
// later release.
type Buffer interface {
// String returns the log entries in a format that is similar to the
// klog text output.
Expand All @@ -156,32 +126,17 @@ type Buffer interface {
}

// Log contains log entries in the order in which they were generated.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type Log []LogEntry

// DeepCopy returns a copy of the log. The error instance and key/value
// pairs remain shared.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func (l Log) DeepCopy() Log {
log := make(Log, 0, len(l))
log = append(log, l...)
return log
}

// LogEntry represents all information captured for a log entry.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type LogEntry struct {
// Timestamp stores the time when the log entry was created.
Timestamp time.Time
Expand Down Expand Up @@ -214,38 +169,18 @@ type LogEntry struct {

// LogType determines whether a log entry was created with an Error or Info
// call.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type LogType string

const (
// LogError is the special value used for Error log entries.
//
// Experimental
//
// Notice: This value is EXPERIMENTAL and may be changed or removed in
// a later release.
LogError = LogType("ERROR")

// LogInfo is the special value used for Info log entries.
//
// Experimental
//
// Notice: This value is EXPERIMENTAL and may be changed or removed in
// a later release.
LogInfo = LogType("INFO")
)

// Underlier is implemented by the LogSink of this logger. It provides access
// to additional APIs that are normally hidden behind the Logger API.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type Underlier interface {
// GetUnderlying returns the testing instance that logging goes to.
// It returns nil when the test has completed already.
Expand Down
27 changes: 0 additions & 27 deletions test/output.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,6 @@ limitations under the License.
*/

// Package test contains a reusable unit test for logging output and behavior.
//
// # Experimental
//
// Notice: This package is EXPERIMENTAL and may be changed or removed in a
// later release.
package test

import (
Expand Down Expand Up @@ -48,11 +43,6 @@ import (
//
// The returned flag set has the klog flags registered. It can
// be used to make further changes to the klog configuration.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func InitKlog(tb testing.TB) *flag.FlagSet {
state := klog.CaptureState()
tb.Cleanup(state.Restore)
Expand All @@ -77,11 +67,6 @@ func InitKlog(tb testing.TB) *flag.FlagSet {
}

// OutputConfig contains optional settings for Output.
//
// # Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type OutputConfig struct {
// NewLogger is called to create a new logger. If nil, output via klog
// is tested. Support for -vmodule is optional. ClearLogger is called
Expand Down Expand Up @@ -553,12 +538,6 @@ var _, _, printWithKlogLine, _ = runtime.Caller(0) // anchor for finding the lin
//
// Loggers will be tested with direct calls to Info or
// as backend for klog.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release. The test cases and thus the expected output also may
// change.
func Output(t *testing.T, config OutputConfig) {
for n, test := range tests {
t.Run(n, func(t *testing.T) {
Expand Down Expand Up @@ -879,12 +858,6 @@ func Output(t *testing.T, config OutputConfig) {
//
// Loggers will be tested with direct calls to Info or
// as backend for klog.
//
// # Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release. The test cases and thus the expected output also may
// change.
func Benchmark(b *testing.B, config OutputConfig) {
for n, test := range tests {
b.Run(n, func(b *testing.B) {
Expand Down
10 changes: 0 additions & 10 deletions test/zapr.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,6 @@ package test

// ZaprOutputMappingDirect provides a mapping from klog output to the
// corresponding zapr output when zapr is called directly.
//
// # Experimental
//
// Notice: This package is EXPERIMENTAL and may be changed or removed in a
// later release.
func ZaprOutputMappingDirect() map[string]string {
return map[string]string{
`I output.go:<LINE>] "test" akey="<&>"
Expand Down Expand Up @@ -282,11 +277,6 @@ I output.go:<LINE>] "odd WithValues" keyWithoutValue="(MISSING)"
// - zap drops keys with missing values, here we get "(MISSING)".
// - zap does not de-duplicate key/value pairs, here klog does that
// for it.
//
// # Experimental
//
// Notice: This package is EXPERIMENTAL and may be changed or removed in a
// later release.
func ZaprOutputMappingIndirect() map[string]string {
mapping := ZaprOutputMappingDirect()

Expand Down

0 comments on commit 18cdd3a

Please sign in to comment.