integration

README

Integration Tests

Integration tests should be used to test a specific functionality of k3s that exists across multiple Go packages, either via exported function calls, or more often, CLI commands. Integration tests should be used for "black box" testing.

Framework

All integration tests in K3s follow a Behavior Diven Development (BDD) style. Specifically, K3s uses Ginkgo and Gomega to drive the tests.
To generate an initial test, the command ginkgo bootstrap can be used.

To facilitate K3s CLI testing, see tests/util/cmd.go helper functions.

Format

All integration tests should be placed under tests/integration/<TEST_NAME>.
All integration test files should be named: <TEST_NAME>_int_test.go.
All integration test functions should be named: Test_Integration<TEST_NAME>.
See the local storage test as an example.

Running

Integration tests can be run with no k3s cluster present, each test will spin up and kill the appropriate k3s server it needs.
Note: Integration tests must be run as root, prefix the commands below with sudo -E env "PATH=$PATH" if a sudo user.

go test ./tests/integration/... -run Integration

Additionally, to generate JUnit reporting for the tests, the Ginkgo CLI is used

ginkgo --junit-report=result.xml ./tests/integration/...

Integration tests can be run on an existing single-node cluster via compile time flag, tests will skip if the server is not configured correctly.

go test -ldflags "-X 'github.com/k3s-io/k3s/tests/integration.existingServer=True'" ./tests/integration/... -run Integration

Integration tests can also be run via a Sonobuoy plugin on an existing single-node cluster.

./scripts/build-tests-sonobuoy
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml sonobuoy run --plugin ./dist/artifacts/k3s-int-tests.yaml

Check the sonobuoy status and retrieve results

sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml sonobuoy status
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml sonobuoy retrieve
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml sonobuoy results <TAR_FILE_FROM_RETRIEVE>

Documentation

Index

• func CheckDeployments(deployments []string) error
• func GetEndpointsAddresses() (string, error)
• func GetPersistentVolume(name string) (*corev1.PersistentVolume, error)
• func GetPersistentVolumeClaim(namespace, name string) (*corev1.PersistentVolumeClaim, error)
• func GetPod(namespace, name string) (*corev1.Pod, error)
• func IsExistingServer() bool
• func IsRoot() bool
• func K3sCleanup(k3sTestLock int, dataDir string) error
• func K3sCmd(inputArgs ...string) (string, error)
• func K3sDefaultDeployments() error
• func K3sKillServer(server *K3sServer) error
• func K3sSaveLog(server *K3sServer, dump bool) error
• func K3sServerArgs() []string
• func K3sStopServer(server *K3sServer) error
• func K3sTestLock() (int, error)
• func ParseNodes() ([]corev1.Node, error)
• func ParsePods(namespace string, opts metav1.ListOptions) ([]corev1.Pod, error)
• func RunCommand(cmd string) (string, error)
• func SearchK3sLog(k3s *K3sServer, target string) (bool, error)
• func ServerArgsPresent(neededArgs []string) bool
• type K3sServer
  • func K3sStartServer(inputArgs ...string) (*K3sServer, error)

Functions

func CheckDeployments

func CheckDeployments(deployments []string) error

CheckDeployments checks if the provided list of deployments are ready, otherwise returns an error

func GetEndpointsAddresses

func GetEndpointsAddresses() (string, error)

func GetPersistentVolume

func GetPersistentVolume(name string) (*corev1.PersistentVolume, error)

func GetPersistentVolumeClaim

func GetPersistentVolumeClaim(namespace, name string) (*corev1.PersistentVolumeClaim, error)

func GetPod

func GetPod(namespace, name string) (*corev1.Pod, error)

func IsExistingServer

func IsExistingServer() bool

func IsRoot

func IsRoot() bool

IsRoot return true if the user is root (UID 0)

func K3sCleanup

func K3sCleanup(k3sTestLock int, dataDir string) error

K3sCleanup unlocks the test-lock and attempts to cleanup networking and files leftover from an integration test. This is similar to the k3s-killall.sh script, but we dynamically generate that on install, so we don't have access to it during testing.

func K3sCmd

func K3sCmd(inputArgs ...string) (string, error)

K3sCmd launches the provided K3s command via exec. Command blocks until finished. Command output from both Stderr and Stdout is provided via string. Input can be a single string with space separated args, or multiple string args cmdEx1, err := K3sCmd("etcd-snapshot", "ls") cmdEx2, err := K3sCmd("kubectl get pods -A") cmdEx2, err := K3sCmd("kubectl", "get", "pods", "-A")

func K3sDefaultDeployments

func K3sDefaultDeployments() error

K3sDefaultDeployments checks if the default deployments for K3s are ready, otherwise returns an error

func K3sKillServer

func K3sKillServer(server *K3sServer) error

K3sKillServer terminates the running K3s server and its children. Equivalent to k3s-killall.sh

func K3sSaveLog

func K3sSaveLog(server *K3sServer, dump bool) error

func K3sServerArgs

func K3sServerArgs() []string

K3sServerArgs returns the list of arguments that the k3s server launched with

func K3sStopServer

func K3sStopServer(server *K3sServer) error

K3sStopServer gracefully stops the running K3s server and does not kill its children. Equivalent to stopping the K3s service

func K3sTestLock

func K3sTestLock() (int, error)

func ParseNodes

func ParseNodes() ([]corev1.Node, error)

func ParsePods

func ParsePods(namespace string, opts metav1.ListOptions) ([]corev1.Pod, error)

func RunCommand

func RunCommand(cmd string) (string, error)

RunCommand Runs command on the host

func SearchK3sLog

func SearchK3sLog(k3s *K3sServer, target string) (bool, error)

func ServerArgsPresent

func ServerArgsPresent(neededArgs []string) bool

ServerArgsPresent checks if the given arguments are found in the running k3s server

Types

type K3sServer

type K3sServer struct {
	// contains filtered or unexported fields
}

func K3sStartServer

func K3sStartServer(inputArgs ...string) (*K3sServer, error)

K3sStartServer acquires an exclusive lock on a temporary file, then launches a k3s cluster with the provided arguments. Subsequent/parallel calls to this function will block until the original lock is cleared using K3sKillServer