1# Overview
2
3The Kubernetes E2E framework simplifies writing Ginkgo tests suites. It's main
4usage 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
11Usage of the framework outside of Kubernetes is possible, but not encouraged.
12Downstream users have to be prepared to deal with API changes.
13
14# Code Organization
15
16The core framework is the `k8s.io/kubernetes/test/e2e/framework` package. It
17contains 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
24It also contains a `TestContext` with settings that can be controlled via
25command line flags. For historic reasons, this also contains settings for
26individual tests or packages that are not part of the core framework.
27
28Optional functionality is placed in sub packages like
29`test/e2e/framework/pod`. The core framework does not depend on those. Sub
30packages may depend on the core framework.
31
32The 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
39When a test suite gets invoked, the top-level `Describe` calls register the
40callbacks that define individual tests, but does not invoke them yet. After
41that init phase, command line flags are parsed and the `Describe` callbacks are
42invoked. Those then define the actual tests for the test suite. Command line
43flags can be used to influence the test definitions.
44
45Now `Context/BeforeEach/AfterEach/It` define code that will be called later
46when executing a specific test. During this setup phase, `f :=
47framework.NewDefaultFramework("some tests")` creates a `Framework` instance for
48one or more tests. `NewDefaultFramework` initializes that instance anew for
49each test with a `BeforeEach` callback. Starting with Kubernetes 1.26, that
50instance gets cleaned up after all other code for a test has been invoked, so
51the following code is correct:
52
53```
54f := framework.NewDefaultFramework("some tests")
55
56ginkgo.AfterEach(func() {
57 # Do something with f.ClientSet.
58}
59
60ginkgo.It("test something", func(ctx context.Context) {
61 # The actual test.
62})
63```
64
65Optional functionality can be injected into each test by adding a callback to
66`NewFrameworkExtensions` in an init function. `NewDefaultFramework` will invoke
67those callbacks as if the corresponding code had been added to each test like this:
68
69```
70f := framework.NewDefaultFramework("some tests")
71
72optional.SomeCallback(f)
73```
74
75`SomeCallback` then can register additional `BeforeEach` or `AfterEach`
76callbacks that use the test's `Framework` instance.
77
78When a test runs, callbacks defined for it with `BeforeEach` and `AfterEach`
79are called in first-in-first-out order. Since the migration to ginkgo v2 in
80Kubernetes 1.25, the `AfterEach` callback is called also when there has been a
81test failure. This can be used to run cleanup code for a test
82reliably. However,
83[`ginkgo.DeferCleanup`](https://onsi.github.io/ginkgo/#spec-cleanup-aftereach-and-defercleanup)
84is often a better alternative. Its callbacks are executed in first-in-last-out
85order.
86
87`test/e2e/framework/internal/unittests/cleanup/cleanup.go` shows how these
88different callbacks can be used and in which order they are going to run.
View as plain text