Skip to content

A Go framework for end-to-end testing of components running in Kubernetes clusters.

License

Notifications You must be signed in to change notification settings

kubernetes-sigs/e2e-framework

Folders and files

NameName
Last commit message
Last commit date
Jan 21, 2025
Feb 10, 2024
Jan 15, 2025
Jan 15, 2025
Jan 15, 2025
Jan 15, 2025
Jan 15, 2025
Jan 15, 2025
Jan 26, 2024
May 8, 2024
Feb 16, 2022
Jul 1, 2023
Oct 20, 2020
Oct 20, 2020
Jul 10, 2023
Apr 10, 2024
Nov 25, 2024
Oct 20, 2020
Oct 20, 2020
Oct 20, 2020
Oct 20, 2020
Jan 24, 2025
Jan 24, 2025

E2E Framework

godoc

A Go framework for end-to-end testing of components running in Kubernetes clusters.

The primary goal of this project is to provide a go test(able) framework that uses the native Go testing API to define end-to-end tests suites that can be used to test Kubernetes components. Some additional goals include:

  • Provide a sensible programmatic API to compose tests
  • Leverage Go's testing API to compose test suites
  • Expose packages that are easy to programmatically consume
  • Collection of helper functions that abstracts Client-Go functionalities
  • Rely on built-in Go test features to easily select/filter tests to run during execution
  • And more

For more detail, see the design document.

Getting started

The Go package is designed to be integrated directly in your test. Simply update your project to pull the desired Go modules:

go get sigs.k8s.io/e2e-framework/pkg/env
go get sigs.k8s.io/e2e-framework/klient

Using the framework

The framework uses the built-in Go testing framework directly to define and run tests.

Setup TestMain

Use function TestMain to define package-wide testing steps and configure behavior. The following examples uses pre-defined steps to create a KinD cluster before running any test in the package:

var (
	testenv env.Environment
)

func TestMain(m *testing.M) {
	testenv = env.New()
	kindClusterName := envconf.RandomName("my-cluster", 16)
	namespace := envconf.RandomName("myns", 16)

	// Use pre-defined environment funcs to create a kind cluster prior to test run
	testenv.Setup(
		envfuncs.CreateCluster(kind.NewProvider(), kindClusterName),
		envfuncs.CreateNamespace(namespace),
	)

	// Use pre-defined environment funcs to teardown kind cluster after tests
	testenv.Finish(
		envfuncs.DeleteNamespace(namespace),
		envfuncs.DestroyCluster(kindClusterName),
	)

	// launch package tests
	os.Exit(testenv.Run(m))
}

Define a test function

Use a Go test function to define features to be tested as shown below:

func TestKubernetes(t *testing.T) {
    f1 := features.New("count pod").
        WithLabel("type", "pod-count").
        Assess("pods from kube-system", func(ctx context.Context, t *testing.T, cfg *envconf.Config) context.Context {
            var pods corev1.PodList
            err := cfg.Client().Resources("kube-system").List(context.TODO(), &pods)
            if err != nil {
                t.Fatal(err)
            }
            if len(pods.Items) == 0 {
                t.Fatal("no pods in namespace kube-system")
            }
            return ctx
        }).Feature()

    f2 := features.New("count namespaces").
        WithLabel("type", "ns-count").
        Assess("namespace exist", func(ctx context.Context, t *testing.T, cfg *envconf.Config) context.Context {
            var nspaces corev1.NamespaceList
            err := cfg.Client().Resources().List(context.TODO(), &nspaces)
            if err != nil {
                t.Fatal(err)
            }
            if len(nspaces.Items) == 1 {
                t.Fatal("no other namespace")
            }
            return ctx
        }).Feature()

    // test feature
    testenv.Test(t, f1, f2)
}

Running the test

Use the Go testing tooling to run the tests in the package as shown below. The following would run all tests except those with label type=ns-count:

go test ./package -args --skip-labels="type=ns-count"

Examples

See the ./examples directory for additional examples showing how to use the framework.

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the community page.

You can reach the maintainers of this project at:

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.