knative.dev/pkg@v0.0.0-20260602142205-ac97e43f6622/test/upgrade/types.go (about)

     1  /*
     2  Copyright 2020 The Knative Authors
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package upgrade
    18  
    19  import (
    20  	"testing"
    21  	"time"
    22  
    23  	"go.uber.org/zap"
    24  )
    25  
    26  // Suite represents a upgrade tests suite that can be executed and will perform
    27  // execution in predictable manner.
    28  type Suite struct {
    29  	Tests         Tests
    30  	Installations Installations
    31  }
    32  
    33  // Tests holds a list of operations for various part of upgrade suite.
    34  type Tests struct {
    35  	PreUpgrade    []Operation
    36  	PostUpgrade   []Operation
    37  	PostDowngrade []Operation
    38  	Continual     []BackgroundOperation
    39  }
    40  
    41  // Installations holds a list of operations that will install Knative components
    42  // in different versions.
    43  type Installations struct {
    44  	Base          []Operation
    45  	UpgradeWith   []Operation
    46  	DowngradeWith []Operation
    47  }
    48  
    49  // Operation represents a upgrade test operation like test or installation that
    50  // can be provided by specific component or reused in aggregating components.
    51  type Operation interface {
    52  	// Name is a human readable operation title, and it will be used in t.Run.
    53  	Name() string
    54  	// Handler is a function that will be called to perform an operation.
    55  	Handler() func(c Context)
    56  }
    57  
    58  // BackgroundOperation represents a upgrade test operation that will be
    59  // performed in background while other operations is running. To achieve that
    60  // a passed BackgroundContext should be used to synchronize it's operations with
    61  // Ready and Stop channels.
    62  type BackgroundOperation interface {
    63  	// Name is a human readable operation title, and it will be used in t.Run.
    64  	Name() string
    65  	// Setup method may be used to set up environment before upgrade/downgrade is
    66  	// performed.
    67  	Setup() func(c Context)
    68  	// Handler will be executed in background while upgrade/downgrade is being
    69  	// executed. It can be used to constantly validate environment during that
    70  	// time and/or wait for StopEvent being sent. After StopEvent is received
    71  	// user should validate environment, clean up resources, and report found
    72  	// issues to testing.T forwarded in StepEvent.
    73  	Handler() func(bc BackgroundContext)
    74  }
    75  
    76  // Context is an object that is passed to every operation. It contains testing.T
    77  // for error reporting and zap.SugaredLogger for unbuffered logging.
    78  type Context struct {
    79  	T   *testing.T
    80  	Log *zap.SugaredLogger
    81  }
    82  
    83  // BackgroundContext is a upgrade test execution context that will be passed
    84  // down to each handler of BackgroundOperation. It contains a stop event channel.
    85  // Until stop event is sent user may use zap.SugaredLogger to log state of execution if
    86  // necessary.
    87  type BackgroundContext struct {
    88  	T    *testing.T
    89  	Log  *zap.SugaredLogger
    90  	Stop <-chan struct{}
    91  }
    92  
    93  // WaitForStopEventConfiguration holds a values to be used be WaitForStopEvent
    94  // function. OnStop will be called when a stop event is sent. OnWait will be
    95  // invoked in a loop while waiting, and each wait act is driven by WaitTime
    96  // amount.
    97  type WaitForStopEventConfiguration struct {
    98  	Name     string
    99  	OnStop   func()
   100  	OnWait   func(bc BackgroundContext, self WaitForStopEventConfiguration)
   101  	WaitTime time.Duration
   102  }
   103  
   104  // Configuration holds required and optional configuration to run upgrade tests.
   105  type Configuration struct {
   106  	T *testing.T
   107  	LogConfig
   108  }
   109  
   110  // LogConfig holds the logger configuration. It allows for passing just the
   111  // logger configuration options.
   112  type LogConfig struct {
   113  	// Config from which the zap.Logger be created.
   114  	// Deprecated: This config doesn't have effect. Use Options instead.
   115  	Config zap.Config
   116  	// Options holds options for the zap.Logger.
   117  	Options []zap.Option
   118  }
   119  
   120  // SuiteExecutor is to execute upgrade test suite.
   121  type SuiteExecutor interface {
   122  	Execute(c Configuration)
   123  }