|
| 1 | +# Integration Tests |
| 2 | + |
| 3 | +This document outlines how to run, debug and add new integration tests for steve. |
| 4 | + |
| 5 | +## Dependencies |
| 6 | + |
| 7 | +To run the integration tests, you will need a running Kubernetes cluster. The tests will automatically target the cluster configured in your `KUBECONFIG` environment variable. |
| 8 | + |
| 9 | +If you do not have a cluster configured, the tests will attempt to create a local one for you using [k3d](https://k3d.io/v5.6.0/#installation). This requires the following tools to be installed: |
| 10 | + |
| 11 | +- [docker](https://docs.docker.com/get-docker/) |
| 12 | +- [k3d](https://k3d.io/v5.6.0/#installation) |
| 13 | + |
| 14 | +You will also need [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) to be installed and available in your `PATH`. |
| 15 | + |
| 16 | +## Running the tests |
| 17 | + |
| 18 | +The integration tests can be run by executing the following command: |
| 19 | + |
| 20 | +```sh |
| 21 | +make integration-tests |
| 22 | +``` |
| 23 | + |
| 24 | +This will: |
| 25 | +1. Connect to the Kubernetes cluster defined by your `KUBECONFIG` environment variable. If no cluster is configured, it will try to create a `k3d` cluster named `steve-integration-test`. |
| 26 | +2. Run the Go tests located in the `tests/` directory. |
| 27 | + |
| 28 | +## Debugging |
| 29 | + |
| 30 | +It is possible to pause the execution of a test to manually inspect the state of the cluster, the steve API and the SQLite database. This can be achieved by setting `INTEGRATION_TEST_DEBUG=true`: |
| 31 | + |
| 32 | +```sh |
| 33 | +INTEGRATION_TEST_DEBUG=true make integration-tests |
| 34 | +``` |
| 35 | + |
| 36 | +When a test is finished, it will print the following information and block until the test is cancelled (e.g. with `Ctrl+C`): |
| 37 | + |
| 38 | +``` |
| 39 | +########################### |
| 40 | +# |
| 41 | +# Integration tests stopped as requested |
| 42 | +# |
| 43 | +# You can now access the Kubernetes cluster and steve |
| 44 | +# |
| 45 | +# Kubernetes: KUBECONFIG=<path to kubeconfig> |
| 46 | +# Steve URL: <steve API endpoint> |
| 47 | +# SQL cache database: <path to sqlite database> |
| 48 | +# |
| 49 | +########################### |
| 50 | +``` |
| 51 | + |
| 52 | +You can then use this information to interact with the Kubernetes cluster and the steve API. |
| 53 | + |
| 54 | +## Adding new tests |
| 55 | + |
| 56 | +The integration tests are written using the `testify/suite` package. The main suite is `IntegrationSuite` in `integration_test.go`. |
| 57 | + |
| 58 | +Tests are data-driven and rely on `.test.yaml` files located in the `testdata` directory. These YAML files contain both the Kubernetes resources to apply and the configuration for the test assertions. |
| 59 | + |
| 60 | +To add a new test scenario, you can follow the example of `column_test.go` and `testdata/columns/`: |
| 61 | + |
| 62 | +1. Create a new `my_feature_test.go` file in the `tests/` directory. |
| 63 | +2. Create a new directory `testdata/my_feature/`. |
| 64 | +3. Add a new test function to the `IntegrationSuite`, for example `TestMyFeature`, in your new Go file. |
| 65 | +4. In this function, you will typically: |
| 66 | + - Set up a `httptest.NewServer` with the steve API handler. |
| 67 | + - Find your test scenarios by looking for `.test.yaml` files in `testdata/my_feature/`. |
| 68 | + - For each scenario, run a subtest. |
| 69 | +5. Each subtest should: |
| 70 | + - Parse the `.test.yaml` file. The file can contain a header with test configuration and Kubernetes objects separated by `---`. |
| 71 | + - Apply the Kubernetes objects to the cluster. |
| 72 | + - Make requests to the steve API. |
| 73 | + - Assert that the responses are correct based on the test configuration. |
| 74 | + - Ensure that `defer i.maybeStopAndDebug(baseURL)` is called to allow for debugging. |
0 commit comments