knuu

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
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

Docker: Knuu requires Docker to run

You can install Docker by following the instructions here.
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.
'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:

Add the following to your go.mod file:

require (
    github.com/celestiaorg/knuu v0.7.0
    github.com/stretchr/testify v1.8.4
)

Run go mod tidy to download the dependencies.

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

package main

import (
    "fmt"
    "github.com/celestiaorg/knuu/pkg/knuu"
    "os"
    "testing"
    "time"
)

func TestMain(m *testing.M) {
    t := time.Now()
    identifier := fmt.Sprintf("%s_%03d", t.Format("20060102_150405"), t.Nanosecond()/1e6)
    err := knuu.InitializeWithIdentifier(identifier)
    if err != nil {
       log.Fatalf("Error initializing knuu: %v:", err)
    }
    exitVal := m.Run()
    os.Exit(exitVal)
}

Create a file called example_test.go with the following content:

package main

import (
    "github.com/celestiaorg/knuu/pkg/knuu"
    "github.com/stretchr/testify/assert"
    "os"
    "testing"
)

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.

Frenzoid / knuu