equalobject.go

Documentation: sigs.k8s.io/controller-runtime/pkg/envtest/komega

     1  /*
     2  Copyright 2022 The Kubernetes 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      http://www.apache.org/licenses/LICENSE-2.0
     8  Unless required by applicable law or agreed to in writing, software
     9  distributed under the License is distributed on an "AS IS" BASIS,
    10  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    11  See the License for the specific language governing permissions and
    12  limitations under the License.
    13  */
    14  
    15  package komega
    16  
    17  import (
    18  	"fmt"
    19  	"reflect"
    20  	"strings"
    21  
    22  	"github.com/google/go-cmp/cmp"
    23  	"github.com/onsi/gomega/format"
    24  	"github.com/onsi/gomega/types"
    25  	"k8s.io/apimachinery/pkg/runtime"
    26  )
    27  
    28  // These package variables hold pre-created commonly used options that can be used to reduce the manual work involved in
    29  // identifying the paths that need to be compared for testing equality between objects.
    30  var (
    31  	// IgnoreAutogeneratedMetadata contains the paths for all the metadata fields that are commonly set by the
    32  	// client and APIServer. This is used as a MatchOption for situations when only user-provided metadata is relevant.
    33  	IgnoreAutogeneratedMetadata = IgnorePaths{
    34  		"metadata.uid",
    35  		"metadata.generation",
    36  		"metadata.creationTimestamp",
    37  		"metadata.resourceVersion",
    38  		"metadata.managedFields",
    39  		"metadata.deletionGracePeriodSeconds",
    40  		"metadata.deletionTimestamp",
    41  		"metadata.selfLink",
    42  		"metadata.generateName",
    43  	}
    44  )
    45  
    46  type diffPath struct {
    47  	types []string
    48  	json  []string
    49  }
    50  
    51  // equalObjectMatcher is a Gomega matcher used to establish equality between two Kubernetes runtime.Objects.
    52  type equalObjectMatcher struct {
    53  	// original holds the object that will be used to Match.
    54  	original runtime.Object
    55  
    56  	// diffPaths contains the paths that differ between two objects.
    57  	diffPaths []diffPath
    58  
    59  	// options holds the options that identify what should and should not be matched.
    60  	options *EqualObjectOptions
    61  }
    62  
    63  // EqualObject returns a Matcher for the passed Kubernetes runtime.Object with the passed Options. This function can be
    64  // used as a Gomega Matcher in Gomega Assertions.
    65  func EqualObject(original runtime.Object, opts ...EqualObjectOption) types.GomegaMatcher {
    66  	matchOptions := &EqualObjectOptions{}
    67  	matchOptions = matchOptions.ApplyOptions(opts)
    68  
    69  	return &equalObjectMatcher{
    70  		options:  matchOptions,
    71  		original: original,
    72  	}
    73  }
    74  
    75  // Match compares the current object to the passed object and returns true if the objects are the same according to
    76  // the Matcher and MatchOptions.
    77  func (m *equalObjectMatcher) Match(actual interface{}) (success bool, err error) {
    78  	// Nil checks required first here for:
    79  	//     1) Nil equality which returns true
    80  	//     2) One object nil which returns an error
    81  	actualIsNil := reflect.ValueOf(actual).IsNil()
    82  	originalIsNil := reflect.ValueOf(m.original).IsNil()
    83  
    84  	if actualIsNil && originalIsNil {
    85  		return true, nil
    86  	}
    87  	if actualIsNil || originalIsNil {
    88  		return false, fmt.Errorf("can not compare an object with a nil. original %v , actual %v", m.original, actual)
    89  	}
    90  
    91  	m.diffPaths = m.calculateDiff(actual)
    92  	return len(m.diffPaths) == 0, nil
    93  }
    94  
    95  // FailureMessage returns a message comparing the full objects after an unexpected failure to match has occurred.
    96  func (m *equalObjectMatcher) FailureMessage(actual interface{}) (message string) {
    97  	return fmt.Sprintf("the following fields were expected to match but did not:\n%v\n%s", m.diffPaths,
    98  		format.Message(actual, "expected to match", m.original))
    99  }
   100  
   101  // NegatedFailureMessage returns a string stating that all fields matched, even though that was not expected.
   102  func (m *equalObjectMatcher) NegatedFailureMessage(actual interface{}) (message string) {
   103  	return "it was expected that some fields do not match, but all of them did"
   104  }
   105  
   106  func (d diffPath) String() string {
   107  	return fmt.Sprintf("(%s/%s)", strings.Join(d.types, "."), strings.Join(d.json, "."))
   108  }
   109  
   110  // diffReporter is a custom recorder for cmp.Diff which records all paths that are
   111  // different between two objects.
   112  type diffReporter struct {
   113  	stack []cmp.PathStep
   114  
   115  	diffPaths []diffPath
   116  }
   117  
   118  func (r *diffReporter) PushStep(s cmp.PathStep) {
   119  	r.stack = append(r.stack, s)
   120  }
   121  
   122  func (r *diffReporter) Report(res cmp.Result) {
   123  	if !res.Equal() {
   124  		r.diffPaths = append(r.diffPaths, r.currentPath())
   125  	}
   126  }
   127  
   128  // currentPath converts the current stack into string representations that match
   129  // the IgnorePaths and MatchPaths syntax.
   130  func (r *diffReporter) currentPath() diffPath {
   131  	p := diffPath{types: []string{""}, json: []string{""}}
   132  	for si, s := range r.stack[1:] {
   133  		switch s := s.(type) {
   134  		case cmp.StructField:
   135  			p.types = append(p.types, s.String()[1:])
   136  			// fetch the type information from the parent struct.
   137  			// Note: si has an offset of 1 compared to r.stack as we loop over r.stack[1:], so we don't need -1
   138  			field := r.stack[si].Type().Field(s.Index())
   139  			p.json = append(p.json, strings.Split(field.Tag.Get("json"), ",")[0])
   140  		case cmp.SliceIndex:
   141  			key := fmt.Sprintf("[%d]", s.Key())
   142  			p.types[len(p.types)-1] += key
   143  			p.json[len(p.json)-1] += key
   144  		case cmp.MapIndex:
   145  			key := fmt.Sprintf("%v", s.Key())
   146  			if strings.ContainsAny(key, ".[]/\\") {
   147  				key = fmt.Sprintf("[%s]", key)
   148  				p.types[len(p.types)-1] += key
   149  				p.json[len(p.json)-1] += key
   150  			} else {
   151  				p.types = append(p.types, key)
   152  				p.json = append(p.json, key)
   153  			}
   154  		}
   155  	}
   156  	// Empty strings were added as the first element. If they're still empty, remove them again.
   157  	if len(p.json) > 0 && len(p.json[0]) == 0 {
   158  		p.json = p.json[1:]
   159  		p.types = p.types[1:]
   160  	}
   161  	return p
   162  }
   163  
   164  func (r *diffReporter) PopStep() {
   165  	r.stack = r.stack[:len(r.stack)-1]
   166  }
   167  
   168  // calculateDiff calculates the difference between two objects and returns the
   169  // paths of the fields that do not match.
   170  func (m *equalObjectMatcher) calculateDiff(actual interface{}) []diffPath {
   171  	var original interface{} = m.original
   172  	// Remove the wrapping Object from unstructured.Unstructured to make comparison behave similar to
   173  	// regular objects.
   174  	if u, isUnstructured := actual.(runtime.Unstructured); isUnstructured {
   175  		actual = u.UnstructuredContent()
   176  	}
   177  	if u, ok := m.original.(runtime.Unstructured); ok {
   178  		original = u.UnstructuredContent()
   179  	}
   180  	r := diffReporter{}
   181  	cmp.Diff(original, actual, cmp.Reporter(&r))
   182  	return filterDiffPaths(*m.options, r.diffPaths)
   183  }
   184  
   185  // filterDiffPaths filters the diff paths using the paths in EqualObjectOptions.
   186  func filterDiffPaths(opts EqualObjectOptions, paths []diffPath) []diffPath {
   187  	result := []diffPath{}
   188  
   189  	for _, p := range paths {
   190  		if len(opts.matchPaths) > 0 && !hasAnyPathPrefix(p, opts.matchPaths) {
   191  			continue
   192  		}
   193  		if hasAnyPathPrefix(p, opts.ignorePaths) {
   194  			continue
   195  		}
   196  
   197  		result = append(result, p)
   198  	}
   199  
   200  	return result
   201  }
   202  
   203  // hasPathPrefix compares the segments of a path.
   204  func hasPathPrefix(path []string, prefix []string) bool {
   205  	for i, p := range prefix {
   206  		if i >= len(path) {
   207  			return false
   208  		}
   209  		// return false if a segment doesn't match
   210  		if path[i] != p && (i < len(prefix)-1 || !segmentHasPrefix(path[i], p)) {
   211  			return false
   212  		}
   213  	}
   214  	return true
   215  }
   216  
   217  func segmentHasPrefix(s, prefix string) bool {
   218  	return len(s) >= len(prefix) && s[0:len(prefix)] == prefix &&
   219  		// if it is a prefix match, make sure the next character is a [ for array/map access
   220  		(len(s) == len(prefix) || s[len(prefix)] == '[')
   221  }
   222  
   223  // hasAnyPathPrefix returns true if path matches any of the path prefixes.
   224  // It respects the name boundaries within paths, so 'ObjectMeta.Name' does not
   225  // match 'ObjectMeta.Namespace' for example.
   226  func hasAnyPathPrefix(path diffPath, prefixes [][]string) bool {
   227  	for _, prefix := range prefixes {
   228  		if hasPathPrefix(path.types, prefix) || hasPathPrefix(path.json, prefix) {
   229  			return true
   230  		}
   231  	}
   232  	return false
   233  }
   234  
   235  // EqualObjectOption describes an Option that can be applied to a Matcher.
   236  type EqualObjectOption interface {
   237  	// ApplyToEqualObjectMatcher applies this configuration to the given MatchOption.
   238  	ApplyToEqualObjectMatcher(options *EqualObjectOptions)
   239  }
   240  
   241  // EqualObjectOptions holds the available types of EqualObjectOptions that can be applied to a Matcher.
   242  type EqualObjectOptions struct {
   243  	ignorePaths [][]string
   244  	matchPaths  [][]string
   245  }
   246  
   247  // ApplyOptions adds the passed MatchOptions to the MatchOptions struct.
   248  func (o *EqualObjectOptions) ApplyOptions(opts []EqualObjectOption) *EqualObjectOptions {
   249  	for _, opt := range opts {
   250  		opt.ApplyToEqualObjectMatcher(o)
   251  	}
   252  	return o
   253  }
   254  
   255  // IgnorePaths instructs the Matcher to ignore given paths when computing a diff.
   256  // Paths are written in a syntax similar to Go with a few special cases. Both types and
   257  // json/yaml field names are supported.
   258  //
   259  // Regular Paths:
   260  // * "ObjectMeta.Name"
   261  // * "metadata.name"
   262  // Arrays:
   263  // * "metadata.ownerReferences[0].name"
   264  // Maps, if they do not contain any of .[]/\:
   265  // * "metadata.labels.something"
   266  // Maps, if they contain any of .[]/\:
   267  // * "metadata.labels[kubernetes.io/something]"
   268  type IgnorePaths []string
   269  
   270  // ApplyToEqualObjectMatcher applies this configuration to the given MatchOptions.
   271  func (i IgnorePaths) ApplyToEqualObjectMatcher(opts *EqualObjectOptions) {
   272  	for _, p := range i {
   273  		opts.ignorePaths = append(opts.ignorePaths, strings.Split(p, "."))
   274  	}
   275  }
   276  
   277  // MatchPaths instructs the Matcher to restrict its diff to the given paths. If empty the Matcher will look at all paths.
   278  // Paths are written in a syntax similar to Go with a few special cases. Both types and
   279  // json/yaml field names are supported.
   280  //
   281  // Regular Paths:
   282  // * "ObjectMeta.Name"
   283  // * "metadata.name"
   284  // Arrays:
   285  // * "metadata.ownerReferences[0].name"
   286  // Maps, if they do not contain any of .[]/\:
   287  // * "metadata.labels.something"
   288  // Maps, if they contain any of .[]/\:
   289  // * "metadata.labels[kubernetes.io/something]"
   290  type MatchPaths []string
   291  
   292  // ApplyToEqualObjectMatcher applies this configuration to the given MatchOptions.
   293  func (i MatchPaths) ApplyToEqualObjectMatcher(opts *EqualObjectOptions) {
   294  	for _, p := range i {
   295  		opts.matchPaths = append(opts.ignorePaths, strings.Split(p, "."))
   296  	}
   297  }
   298
View as plain text