From 8304d788bb9fdfa5dc37b9a16fce6a9e5b4c6f3d Mon Sep 17 00:00:00 2001 From: Joe Betz Date: Tue, 10 Feb 2026 16:49:53 -0500 Subject: [PATCH] Explain limitations and maintenance policy of fake client Kubernetes-commit: bce392d1a7dbbe1112d8113ec6539826bfdfcdca --- testing/doc.go | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 testing/doc.go diff --git a/testing/doc.go b/testing/doc.go new file mode 100644 index 000000000..991535703 --- /dev/null +++ b/testing/doc.go @@ -0,0 +1,70 @@ +/* +Copyright 2015 The Kubernetes 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 + + http://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. +*/ + +// Package testing provides a fake Kubernetes client suitable for use in unit +// tests. The fake client simulates interactions with a kube-apiserver without +// requiring one to be running, making tests fast and self-contained. +// +// # Scope and Limitations +// +// This fake client is intentionally simplified. It does not, and will never, +// fully replicate the behavior of a real kube-apiserver. Many server-side +// behaviors such as field defaulting, validation, status management, +// strategic merge patch, server-side apply semantics, and advanced +// field selectors are not supported by this client and there are no plans +// to add them. +// +// This is by design. Maintaining a high-fidelity mock of the entire +// kube-apiserver API surface would introduce significant complexity that is +// difficult to justify for a test utility. +// +// # When to Use This Package +// +// The fake client works well for unit tests that need to verify how your code +// interacts with the Kubernetes API at a structural level, for example: +// +// - Verifying that the correct API calls are made. +// - Supplying canned responses to drive specific code paths. +// +// # When Not to Use This Package +// +// If your tests depend on the kube-apiserver behaving correctly (e.g., +// enforcing validation, persisting resources accurately, handling apply +// semantics, or producing realistic watch events), you should write +// integration tests against a real kube-apiserver instead. +// +// # Contributing +// +// Issues requesting that the fake client more closely match kube-apiserver +// behavior should be limiting to bugs in how the fake behaves for unit test +// scenarios it is clearly intended to support. Pull requests that improve the fake +// client will only be accepted when they meet all of the following criteria: +// +// - The change makes the fake client easier to use for common unit testing +// patterns. +// - The change does not introduce significant complexity to the fake client. +// - The use cases motivating the change are clearly better served by a fake +// client than by integration tests against a real kube-apiserver. +// +// We hold a high bar for these changes. If the test scenarios in question can +// be reasonably addressed through integration testing, we will prefer that +// path over expanding the fake client. +// +// We understand this stance may be inconvenient, and we appreciate your +// understanding. Our goal is to keep this package simple, maintainable, and +// honest about what it provides so that it remains a reliable tool for the +// cases it is designed to handle. +package testing