test

README

ContainerSSH Test Helper Library

This library helps with bringing up services for testing, such as S3, oAuth, etc. All services require an exposed Docker socket to work.

Starting an S3 service

To start the S3 service and then use it with the AWS client as follows:

package your_test

import (
    "testing"

    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/credentials"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
    "github.com/containerssh/test"
)

func TestYourFunc(t *testing.T) {
    s3Service := test.S3(t)

    awsConfig := &aws.Config{
        Credentials: credentials.NewCredentials(
            &credentials.StaticProvider{
                Value: credentials.Value{
                    AccessKeyID:     s3Service.AccessKey(),
                    SecretAccessKey: s3Service.SecretKey(),
                },
            },
        ),
        Endpoint:         aws.String(s3Service.URL()),
        Region:           aws.String(s3Service.Region()),
        S3ForcePathStyle: aws.Bool(s3Service.PathStyle()),
    }
    sess, err := session.NewSession(awsConfig)
    if err != nil {
        t.Fatalf("failed to establish S3 session (%v)", err)
    }
    s3Connection := s3.New(sess)
    
    // ...
}

That's it! Now you have a working S3 connection for testing!

Starting the Kerberos service

You can start the Kerberos service and then use it to authenticate like this:

package your_test

import (
    "fmt"
    "testing"

    "github.com/containerssh/test"
    "github.com/containerssh/gokrb5/v8/client"
    "github.com/containerssh/gokrb5/v8/config"
)

var krbConf = `
[libdefaults]
 dns_lookup_realm = false
 dns_lookup_kdc = false

[realms]
 %s = {
  kdc = 127.0.0.1:88
 }

[domain_realm]
`

func TestKerberos(t *testing.T) {
    krb := test.Kerberos(t)
    
    krbConfig, err := config.NewFromString(fmt.Sprintf(krbConf, krb.Realm()))
    if err != nil {
        t.Fatalf("invalid Kerberos config (%v)", err)
    }
    cli := client.NewWithPassword(
        krb.AdminUsername(),
        krb.Realm(),
        krb.AdminPassword(),
        krbConfig,
    )
    if err := cli.Login(); err != nil {
        t.Fatalf("failed to login (%v)", err)
    }
}

⚠️ Warning! The Kerberos server image is built locally and may take several minutes to build!

👉 Tip: The Kerberos service works locally without DNS lookups, but can also use the test DNS records published under TESTING.CONTAINERSSH.IO. It is recommended that test cases work without DNS lookups.

👉 Tip: You can use the contents of the krb directory to build and start a Kerberos service for testing purposes like this:

docker build -t krb .
docker run \
       --rm \
      -p 127.0.0.1:88:88 \
      -p 127.0.0.1:88:88/udp \
      -e KERBEROS_USERNAME=admin \
      -e KERBEROS_PASSWORD=testing \
      -ti \
      krb

Documentation

Index

• func AssertEquals[T comparable](t *testing.T, got T, expected T)
• func AssertNoError(t *testing.T, err error)
• func AssertNotNil[T comparable](t *testing.T, value T)
• func GetNextPort(t *testing.T, purpose string) int
• func RandomString(length int) string
• type KerberosHelper
  • func Kerberos(t *testing.T) KerberosHelper
• type KubernetesTestConfiguration
  • func Kubernetes(t *testing.T) KubernetesTestConfiguration
• type OIDCServerInstance
  • func OIDCServer(t *testing.T, redirectURI *url.URL) OIDCServerInstance
• type RegistryHelper
  • func Registry(t *testing.T, auth bool) RegistryHelper
• type S3Helper
  • func S3(t *testing.T) S3Helper
• type SSHHelper
  • func SSH(t *testing.T) SSHHelper

Functions

func AssertEquals

func AssertEquals[T comparable](t *testing.T, got T, expected T)

func AssertNoError

func AssertNoError(t *testing.T, err error)

func AssertNotNil

func AssertNotNil[T comparable](t *testing.T, value T)

func GetNextPort

func GetNextPort(t *testing.T, purpose string) int

GetNextPort returns the next free port a test service can bind to.

func RandomString

func RandomString(length int) string

Types

type KerberosHelper

type KerberosHelper interface {
	// Realm returns the Kerberos realm to authenticate with.
	Realm() string
	// KDCHost returns the IP address of the KDC service.
	KDCHost() string
	// KDCPort returns the port number the KDC service is running on.
	KDCPort() int
	// AdminUsername returns a Kerberos username which has admin privileges.
	AdminUsername() string
	// AdminPassword returns the password for the admin username from AdminUsername.
	AdminPassword() string
	// Get service keytab
	Keytab() []byte
}

KerberosHelper is a helper which contains the information about the running Kerberos test service. The individual functions can be used to obtain kerberos parameters.

func Kerberos

func Kerberos(t *testing.T) KerberosHelper

Kerberos starts a new test Kerberos instance. This Kerberos instance is available on the host system. The realm can be obtained from the returned helper object and will be accessible via public DNS. However, to decrease the need to rely on DNS working for your tests you should set up the KDC address explicitly, for example:

var krbConfigTemplate = `[libdefaults]
dns_lookup_realm = false
dns_lookup_kdc = false

[realms]
%s = {
    kdc = %s:%d
}

[domain_realm]`

func TestMe(t *testing.T) {
    krb := test.Kerberos(t)
    krbConfig := fmt.Sprintf(
        krbConfigTemplate,
        krb.Realm(),
        krb.KDCHost(),
        krb.KDCPort(),
    )

    // Do more Kerberos stuff
}

type KubernetesTestConfiguration

type KubernetesTestConfiguration struct {
	// Host contains the IP, IP and port, or URL to connect to.
	Host string
	// ServerName contains the host name against which the servers certificate should be validated.
	ServerName string
	// CACert contains the clusters CA certificate in PEM format.
	CACert string
	// UserCert contains the users certificate in PEM format.
	UserCert string
	// UserKey contains the users private key in PEM format.
	UserKey string
}

KubernetesTestConfiguration holds the credentials to the Kubernetes cluster that can be used for testing.

func Kubernetes

func Kubernetes(t *testing.T) KubernetesTestConfiguration

Kubernetes launches a Kubernetes-in-Docker cluster for testing purposes. The returned string is the path to the kubeconfig file. This function MAY block until enough resources become available to run the Kubernetes cluster. This function MAY return a shared Kubernetes cluster.

type OIDCServerInstance

type OIDCServerInstance interface {
	BaseURL() string
	AuthorizationEndpoint() string
	TokenEndpoint() string
	UserinfoEndpoint() string
	ClientID() string
	ClientSecret() string
}

func OIDCServer

func OIDCServer(
	t *testing.T,
	redirectURI *url.URL,
) OIDCServerInstance

type RegistryHelper

type RegistryHelper interface {
	Port() int
	Username() *string
	Password() *string
}

func Registry

func Registry(t *testing.T, auth bool) RegistryHelper

Registry creates a local Docker registry that can be used for pull tests, optionally with authentication.

type S3Helper

type S3Helper interface {
	// URL returns the endpoint for the S3 connection.
	URL() string
	// AccessKey returns the access key ID that can be used to access the S3 service.
	AccessKey() string
	// SecretKey returns the secret access key that can be used to access the S3 service.
	SecretKey() string
	// Region returns the S3 region string to use.
	Region() string
	// PathStyle returns true if path-style access should be used.
	PathStyle() bool
}

S3Helper gives access to an S3-compatible object storage.

func S3

func S3(t *testing.T) S3Helper

S3 starts up an S3-compatible object storage using Docker for testing, and returns an object that can be queried for connection parameters. When the test finishes it automatically tears down the object storage.

The connection parameters can be fetched from the returned helper object.

type SSHHelper

type SSHHelper interface {
	// Host returns the IP address of the running SSH service.
	Host() string
	// Port returns the port number of the running SSH service.
	Port() int
	// FingerprintSHA256 returns the SHA 256 fingerprint of the server.
	FingerprintSHA256() string
	// HostKey returns the private SSH host key.
	HostKey() []byte
	// Username returns the SSH username to use for connecting.
	Username() string
	// Password returns the SSH password to use for connecting.
	Password() string
	// HostKeyAlgorithms returns a list of usable host key algorithms.
	HostKeyAlgorithms() []string
}

SSHHelper contains the details about a running SSH service.

func SSH

func SSH(t *testing.T) SSHHelper

SSH creates a fully functional SSH service which you can SSH into for testing purposes.