/knuu

Integration Test Framework

Primary LanguageGoApache License 2.0Apache-2.0

knuu

CodeQL License OpenSSF Best Practices

Description

The goal of knuu is to provide a framework for writing integration tests. The framework is written in Go and is designed to be used in Go projects. The idea is to provide a framework that uses the power of containers and Kubernetes without the test writer having to know the details of how to use them.

We invite you to explore our codebase, contribute, and join us in developing a framework to help projects write integration tests.

Features

Knuu is designed around Instances, which you can create, start, control, communicate with other Instances, stop, and destroy.

Some of the features of knuu are:

  • Initialize an Instance from a Container/Docker image
  • Configure startup commands
  • Configure Networking
    • What ports to expose
    • Disable networking to simulate network outages
  • Configure Storage
  • Execute Commands
  • Configure HW resources
  • Create a pool of Instances and control them as a group
  • Allow AddFile after Commit via ConfigMap
  • Implement a TTL value for Pod cleanup
  • Add a timeout variable
  • See this issue for more upcoming features: #91

If you have feedback on the framework, want to report a bug, or suggest an improvement, please create an issue here.

Getting Started

This section will guide you on how to set up and run knuu.

Prerequisites

  1. Docker: Knuu requires Docker to run

    You can install Docker by following the instructions here.

  2. Kubernetes cluster: Set up access to a Kubernetes cluster using a kubeconfig.

    In case you have no Kubernets cluster running yet, you can get more information here.

  3. 'test' Namespace: Create a namespace called 'test' in your Kubernetes cluster.

    Note: The used namespace can be changed by setting the KNUU_NAMESPACE environment variable.

Writing Tests

The documentation you can find here.

Simple example:

  1. Add the following to your go.mod file:

    require (
        github.com/celestiaorg/knuu v0.8.2
        github.com/stretchr/testify v1.8.4
    )
  2. Run go mod tidy to download the dependencies.

  3. Create a file called main_test.go with the following content to initialize knuu:

    package main
    
    import (
        "fmt"
        "os"
        "testing"
        "time"
    
        "github.com/celestiaorg/knuu/pkg/knuu"
    )
    
    func TestMain(m *testing.M) {
        err := knuu.Initialize()
        if err != nil {
           log.Fatalf("Error initializing knuu: %v:", err)
        }
        exitVal := m.Run()
        os.Exit(exitVal)
    }
  4. Create a file called example_test.go with the following content:

    package main
    
    import (
        "os"
        "testing"
    
        "github.com/celestiaorg/knuu/pkg/knuu"
        "github.com/stretchr/testify/assert"
    )
    
    func TestBasic(t *testing.T) {
        t.Parallel()
        // Setup
    
        instance, err := knuu.NewInstance("alpine")
        if err != nil {
            t.Fatalf("Error creating instance '%v':", err)
        }
        err = instance.SetImage("docker.io/alpine:latest")
        if err != nil {
            t.Fatalf("Error setting image: %v", err)
        }
        err = instance.SetCommand("sleep", "infinity")
        if err != nil {
            t.Fatalf("Error setting command: %v", err)
        }
        err = instance.Commit()
        if err != nil {
            t.Fatalf("Error committing instance: %v", err)
        }
    
        t.Cleanup(func() {
            // Cleanup
            if os.Getenv("KNUU_SKIP_CLEANUP") == "true" {
                t.Log("Skipping cleanup")
                return
            }
    
            err = instance.Destroy()
            if err != nil {
                t.Fatalf("Error destroying instance: %v", err)
            }
        })
    
        // Test logic
    
        err = instance.Start()
        if err != nil {
            t.Fatalf("Error starting instance: %v", err)
        }
        err = instance.WaitInstanceIsRunning()
        if err != nil {
            t.Fatalf("Error waiting for instance to be running: %v", err)
        }
        wget, err := instance.ExecuteCommand("echo", "Hello World!")
        if err != nil {
            t.Fatalf("Error executing command '%v':", err)
        }
    
        assert.Equal(t, wget, "Hello World!\n")
    }

You can find more examples in the following repositories:

Running Tests

You can use the built-in go test command to run the tests.

To run all tests in the current directory, you can run:

go test -v ./...

Contributing

We warmly welcome and appreciate contributions.

By participating in this project, you agree to abide by the CNCF Code of Conduct.

See the Contributing Guide for more information.

To ensure that your contribution is working as expected, please run knuu-example with your fork and branch.

Licensing

Knuu is licensed under the Apache License 2.0.