k8s.io/kubernetes@v1.29.3/test/e2e/framework/README.md (about) 1 # Overview 2 3 The Kubernetes E2E framework simplifies writing Ginkgo tests suites. It's main 4 usage is for these tests suites in the Kubernetes repository itself: 5 - test/e2e: runs as client for a Kubernetes cluster. The e2e.test binary is 6 used for conformance testing. 7 - test/e2e_node: runs on the same node as a kubelet instance. Used for testing 8 kubelet. 9 - test/e2e_kubeadm: test suite for kubeadm. 10 11 Usage of the framework outside of Kubernetes is possible, but not encouraged. 12 Downstream users have to be prepared to deal with API changes. 13 14 # Code Organization 15 16 The core framework is the `k8s.io/kubernetes/test/e2e/framework` package. It 17 contains functionality that all E2E suites are expected to need: 18 - connecting to the apiserver 19 - managing per-test namespaces 20 - logging (`Logf`) 21 - failure handling (`Fail`, `Failf`) 22 - writing concise JUnit test results 23 24 It also contains a `TestContext` with settings that can be controlled via 25 command line flags. For historic reasons, this also contains settings for 26 individual tests or packages that are not part of the core framework. 27 28 Optional functionality is placed in sub packages like 29 `test/e2e/framework/pod`. The core framework does not depend on those. Sub 30 packages may depend on the core framework. 31 32 The advantages of splitting the code like this are: 33 - leaner go doc packages by grouping related functions together 34 - not forcing all E2E suites to import all functionality 35 - avoiding import cycles 36 37 # Execution Flow 38 39 When a test suite gets invoked, the top-level `Describe` calls register the 40 callbacks that define individual tests, but does not invoke them yet. After 41 that init phase, command line flags are parsed and the `Describe` callbacks are 42 invoked. Those then define the actual tests for the test suite. Command line 43 flags can be used to influence the test definitions. 44 45 Now `Context/BeforeEach/AfterEach/It` define code that will be called later 46 when executing a specific test. During this setup phase, `f := 47 framework.NewDefaultFramework("some tests")` creates a `Framework` instance for 48 one or more tests. `NewDefaultFramework` initializes that instance anew for 49 each test with a `BeforeEach` callback. Starting with Kubernetes 1.26, that 50 instance gets cleaned up after all other code for a test has been invoked, so 51 the following code is correct: 52 53 ``` 54 f := framework.NewDefaultFramework("some tests") 55 56 ginkgo.AfterEach(func() { 57 # Do something with f.ClientSet. 58 } 59 60 ginkgo.It("test something", func(ctx context.Context) { 61 # The actual test. 62 }) 63 ``` 64 65 Optional functionality can be injected into each test by adding a callback to 66 `NewFrameworkExtensions` in an init function. `NewDefaultFramework` will invoke 67 those callbacks as if the corresponding code had been added to each test like this: 68 69 ``` 70 f := framework.NewDefaultFramework("some tests") 71 72 optional.SomeCallback(f) 73 ``` 74 75 `SomeCallback` then can register additional `BeforeEach` or `AfterEach` 76 callbacks that use the test's `Framework` instance. 77 78 When a test runs, callbacks defined for it with `BeforeEach` and `AfterEach` 79 are called in first-in-first-out order. Since the migration to ginkgo v2 in 80 Kubernetes 1.25, the `AfterEach` callback is called also when there has been a 81 test failure. This can be used to run cleanup code for a test 82 reliably. However, 83 [`ginkgo.DeferCleanup`](https://onsi.github.io/ginkgo/#spec-cleanup-aftereach-and-defercleanup) 84 is often a better alternative. Its callbacks are executed in first-in-last-out 85 order. 86 87 `test/e2e/framework/internal/unittests/cleanup/cleanup.go` shows how these 88 different callbacks can be used and in which order they are going to run.