| name | regression-tests |
| description | Run, scope, or debug telepresence regression tests under regression_test/ — the integration-level suite. Use when the user wants to run an area, suite, or single test, debug a failure, or says "/regression-tests". Runs `go test ./regression_test` scoped with -run, in the background, writing to a log file so heavy output stays out of context. |
regression-tests
Runs the telepresence regression suite from the main conversation, where this
harness's shell-env quirks are known.
Background to assume
- Tests live under
regression_test/ and need a working k8s cluster (kind /
minikube / Docker Desktop) plus images it can reach. For a local cluster set
RTEST_REGISTRY=local and LOAD the images into it rather than pushing.
regression_test/README.md is the reference: fixture-engine rules, the
RTEST_* table, catalogs, labels, coverage. Read it before debugging a
fixture problem.- The shell environment always wins; there is no config file. That means a
stale
export in the user's shell silently changes a run.
Scoping: plain go test -run
Areas are ordinary Go tests, suites and methods are subtests, so one -run
expression selects at any depth:
go test ./regression_test -run '^TestIntercept$'
go test ./regression_test -run '^TestIntercept$/^HeaderFilter$'
go test ./regression_test -run '^TestIntercept$/^HeaderFilter$/^Test_PathPrefix$'
There is no TEST_SUITE/TEST_NAME indirection and no make-argument dance:
inline VAR=value prefixes work in this harness, so run go test directly
and keep make check-regression for the full unscoped suite.
Always pass -count=1 (results must never come from the test cache) and a
-timeout that fits the scope: minutes for one suite, -timeout=100m for a
full run.
The run command
TELEPRESENCE_REGISTRY=local TELEPRESENCE_VERSION=<version> \
RTEST_CONTEXT=<context> RTEST_TEARDOWN=1 \
go test -count=1 -timeout=30m -run '^TestArea$/^Suite$' ./regression_test \
> /tmp/rtest-suite.log 2>&1
RTEST_CONTEXT pins the kube context. Pin it explicitly whenever the
machine has more than one cluster — the default is the kubeconfig's current
context, which is one kubectx away from being the wrong cluster.RTEST_TEARDOWN=1 destroys the run's resources at the end. Without it, dev
mode keeps namespaces, the release, and the connection for the next run to
adopt, which is what makes a scoped rerun take seconds.RTEST_FRESH=1 ignores adoptable resources (use when a previous run left
something suspect). CI implies fresh + teardown.RTEST_LABELS / RTEST_SKIP_LABELS select on compat-core, slow,
stress, flaky-retry.
CRITICAL: a stale TELEPRESENCE_VERSION silently poisons the build
The version under test is read from the binary itself, and make build stamps
it from TELEPRESENCE_VERSION. If the user's shell exports an old value, the
binary gets that version, the manager image tag no longer matches, and the run
fails at image pull with a version that appears nowhere in your command.
Always pass TELEPRESENCE_VERSION explicitly to BOTH make build and the
go test invocation, with the same value.
Rebuild before running
The suite runs the prebuilt binary plus the cluster-side images, so rebuild
whatever changed:
- client-side Go (
pkg/, cmd/telepresence) and any charts/ change:
make build — the chart is go:embedded in the client binary, so a
chart-only edit without a rebuild silently installs the OLD chart.
- manager / agent (
cmd/traffic, charts/): make load-images (or
make load-tel2-image), so the cluster gets the new image.
--docker tests: make client-image — the daemon container runs on the
workstation, so it only needs to exist locally.
RTEST_REGISTRY=local makes the manager use pullPolicy=Never. Reserve
make push-images and a real registry for a remote cluster.
Keep heavy output out of context
This runs in the main thread, so do NOT Read or tail the whole log.
- Launch with
run_in_background: true, redirecting to a fresh path.
- On completion, read only the summary:
grep -E 'passed,|^ok|^--- FAIL|^FAIL' /tmp/rtest-suite.log | tail -5
The runner's own last line is
[rtest] run <stamp>: N passed, N failed, N skipped (N fixture actions).
- For a failure, the per-test artifacts are under
build-output/rtest/logs/<stamp>/<TestPath>/ (cli.log, daemon logs), and
manifest.json records every test's outcome and labels.
Leftover state
make rtest-clean removes everything the framework created, in the cluster
and locally.- A daemon from a killed run:
telepresence quit -s.
- One rtest run per cluster at a time — resource names are stable by design,
which is what makes adoption work.
- A leftover manager from unrelated work ("traffic-manager in namespace X
already manages namespace Y") blocks an unrestricted install: find it with
kubectl get secret -A -l owner=helm, and remember the chart also leaves
cluster-scoped resources (webhook config, ClusterRole/Binding) that
namespace deletion does not remove.
Workflow
- Identify the area/suite: areas are directories under
regression_test/suites/, and each suite is an rt.Suite type registered
in its init().
- Decide the rebuild (see above) and run it with an explicit
TELEPRESENCE_VERSION.
- Run scoped, in the background, to a fresh log path.
- Summarize: the command, pass/fail/skip counts, failing test names, the
smallest excerpt explaining each failure, and the next concrete action.
Don't
- Don't run the full suite unscoped without explicit user instruction — it is
roughly an hour serial;
make check-regression SHARD=1|2|3 runs a third of
it (the shard/area mapping lives in build-aux/main.mk).
- Don't run
go test -list or a deliberately non-matching -run to "check
what exists": the harness provisions real cluster resources before selection,
so it costs a full setup cycle. Grep the suite files instead.
- Don't
make clobber or destroy local images without asking.
- Don't edit generated files:
docs/reference/cli/**, DEPENDENCIES.md,
DEPENDENCY_LICENSES.md, docs/release-notes*.
