Concepts - rancher/shepherd GitHub Wiki

Clients

Clients are used to create the resources in the tests. The advantage of the clients is they register the cleanups with sessions, making resource cleanup trivial.

There are different clients such as;

• The rancher client: is used to create resources on a rancher instance. Given a host URL, and a bearer token the rancher client communicates directly with the rancher instance.

• The dynamic client: is used as a means of communication on a downstream cluster and used for Kubernetes resource management on that cluster.

• The k3d client: is used to create a minimal k3d cluster, this is to give the integration tests the ability to test against a downstream cluster.

You can check the other clients in this directory.

Extensions

Extensions are functions that complete common operations used by tests. Extensions should not require much configuration or support multiple behaviors. Extensions should be simple enough to be used in many tests without needing to be tested themselves.

Wait

Wait is used to monitor resources, and wait for specified conditions. There are multiple ways to wait for a resource. There is WatchWait that uses the watch.Interface of a resource to wait until the check function returns true. For more generic polling or waiting, the "k8s.io/apimachinery/pkg/util/wait" package can be used.

Sessions

Sessions are used to track resources created by tests. A session allows cleanup functions to be registered while it is open. Once a session is closed the cleanup functions will be called latest to oldest. Sessions should be closed after a set of tests that use the same resources is completed. This eliminates the need for each test to create and tear down its resources allowing for more efficient reuse of some resources. When paired with a client sessions are a powerful tool that can track and clean up any resource a test creates with no additional work from the developer.

Configuration

Configuration is loaded from the YAML or JSON file described in CATTLE_TEST_CONFIG. Configuration objects are loaded from their associated key in the configuration file. Default values can also be set on configuration objects.

---

Integration vs Validation

Integration tests - Don't require any external configuration or access to other external services. These should also be short-running as they will run on every PR within CI. Integration tests do not need access keys to cloud providers to run.

Validation tests - Require access to external services and need a config file to run them.

Extensions vs Actions

Extensions are helpers on CRUD commands on singular resources. There are API calls used through the client that require a lot of setup to do a singular CRUD, the extensions are meant to facilitate this. An extension should aim to be generic enough that refactors should not be issued, simply because if an extension requires several refactors it is a big indicator that it is changing because of test flow.

Actions are functions that complete common operations used by tests. Actions don't require much configuration or support multiple behaviors and are usually a combination of CRUD commands to facilitate test setup. Essentially they can be any type of test setup or non-generic CRUD. Actions are anything that combines multiple CRUD commands, is a CRUD or template helper that uses a custom config that specific to the testing, has any sort of test validation that would only work for the testing, or a function that combines the configuration with the CRUD.