e2e/

E2E tests – usage

How to run end-to-end tests, which environment variables to set, and how to manage aux (auxiliary) services. For concepts and guidelines on writing tests, the harness, and aux services, see GUIDELINES.md.

Workflow

You deploy FlightCtl wherever you want using the project’s deployment options: Helm for Kubernetes or OpenShift (see Installing on Kubernetes/OpenShift), or Quadlets (systemd + Podman) for Linux hosts (see deploy/AGENTS.md). Then you prepare (e2e certs and aux services) and run the tests against that deployment.

• Prepare: make prepare-e2e-test, then make start-aux if the tests need registry/git/prometheus.
• Run: make run-e2e-test (set env vars as needed for your deployment; see below).

If you do not have a deployment yet, you can use the local deployment options (same stack, local only):

• Kubernetes (kind): make deploy — creates a kind cluster and deploys FlightCtl there. Then prepare and run as above.
• Quadlet: make deploy-quadlets — deploys FlightCtl via Quadlets on the current host. Then set Quadlet environment vars and run.

The tests only assume that FlightCtl is already running and reachable (cluster or Quadlet).

Prerequisites

• kubectl and kind (if you use make deploy)
• Podman
• Build tools (for agent images, qcow2)
• Optional: libvirt for agent VMs; see suite-specific READMEs (e.g. quadlets/README.md, tpm/README.md, rollout/README.md)

Prepare and run (targets)

Prepare (once or when resetting):

Run (execute tests):

Local deployment (optional):

Aux (start/stop individual services):

Environment variables

Cluster and auth

Filtering and behaviour

Builds and versions

Quadlet environment (running e2e against Quadlet)

When running e2e against a Quadlet deployment (e.g. after make deploy-quadlets on this host or a remote Quadlet host), set:

Other

Filtering the e2e run

# Only the CLI tests
make run-e2e-test GO_E2E_DIRS=test/e2e/cli

# By spec description
make run-e2e-test GINKGO_FOCUS="should create a new project"

# By Ginkgo label (e.g. sanity in CI)
make run-e2e-test GINKGO_LABEL_FILTER="sanity"

Aux (auxiliary) services

Aux services are shared testcontainers used by e2e: registry (TLS on port 5000), git server (SSH on port 2222), Prometheus (port 9090), optionally tracing (Jaeger), and Keycloak (OIDC on port 8080). They run the same for kind and Quadlet; the e2e framework starts them when suites call auxiliary.Get(ctx) or auxiliary.StartServices(ctx, [...]) (or you can start them manually for debugging).

• Start all: make start-aux (after make prepare-e2e-test). This does not include Keycloak; use make start-keycloak for auth-provider tests.
• Stop all: make stop-aux.
• Clean for fresh run: make clean-aux (removes containers and volumes).

The auth-provider suite (test/e2e/authprovider) uses Keycloak to test the OAuth authorization-code flow: it starts Keycloak in BeforeSuite, applies a dynamic OIDC AuthProvider, then runs flightctl login --web --no-browser and automates the Keycloak login page with chromedp. You can run that suite with GO_E2E_DIRS=test/e2e/authprovider; the suite starts Keycloak on its own, or run make start-keycloak first if you prefer.

Registry is at ${IP}:5000 / localhost:5000 (TLS). The test host is configured to treat it as an insecure registry; agents use the CA from test/scripts/create_e2e_certs.sh. See Agent Images for how agent images are built and pushed.

Git server: SSH on port 2222, user user, key bin/.ssh/id_rsa. Example ~/.ssh/config (with flightctl in ~/flightctl):

Host gitserver
     Hostname localhost
     Port 3222
     IdentityFile ~/flightctl/bin/.ssh/id_rsa

Connection allows: create-repo <name>, delete-repo <name>, quit/exit. Clone: git clone user@gitserver:repos/<name>.git.

Example: running against an existing cluster

When your FlightCtl deployment is on a cluster you already have (e.g. OpenShift), prepare once then run:

make prepare-e2e-test
make start-aux   # if suites need registry/git/prometheus

export FLIGHTCTL_NS=flightctl
export KUBEADMIN_PASS=your-oc-password-for-kubeadmin

make run-e2e-test

With a specific CLI/agent RPM:

export FLIGHTCTL_RPM=release/0.3.0
make run-e2e-test

With a Brew build:

export BREW_BUILD_URL=brew-registry-build-url
make run-e2e-test

OpenShift namespace

E2E infra discovers the FlightCtl namespace from the cluster (pods with labels flightctl.service=flightctl-api and flightctl.service=flightctl-worker). Set FLIGHTCTL_NS only when you need to override (e.g. for kubectl create token or CI).

Optional: set E2E_ENVIRONMENT=ocp so the environment is not auto-detected.

OpenShift with shared network (QE)

When the test VM and the OpenShift cluster share a network (e.g. same libvirt network), the cluster can reach aux services on the VM. No in-cluster registry is required.

• Set E2E_ENVIRONMENT=ocp (or rely on context detection). Start aux as usual; suites that need it call auxiliary.Get() and pass registry/git data from the result into the harness and scripts.
• If the test VM has two NICs, set E2E_AUX_HOST to the VM’s IP on the OCP network so registry/git/prometheus are advertised on the interface the cluster can reach:

export FLIGHTCTL_NS=flightctl
export KUBEADMIN_PASS=your-oc-password-for-kubeadmin
export E2E_AUX_HOST=192.168.122.10   # VM IP on the OCP network

make run-e2e-test

OCP test VM (imagebuilder / non-suitable host)

If your host is not suitable for the bootc image builder:

1. Create a test VM: KUBECONFIG_PATH=/path/to/your/kubeconfig make deploy-e2e-ocp-test-vm. Note the SSH command.
2. SSH into the VM and run e2e from inside (see test/README.md for full flow with oc login, then make prepare-e2e-test and make run-e2e-test).

Optional: VM_DISK_SIZE_INC to increase disk size.

More information

• Writing tests, harness, aux: GUIDELINES.md
• Test strategy and integration/unit: ../README.md
• Suite-specific requirements: quadlets/README.md, tpm/README.md, rollout/README.md