Integration Tests
Testing & Qualityintegration-testsIntegration Tests is an Agent Skill for testing & quality published in the telepresenceio/telepresence repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Run, scope, or debug telepresence integration tests under integration_test/. Use when the user wants to run a suite or single test, debug a failing integration test, or says "/integration-tests". Runs `make check-integration` scoped with TEST_SUITE/TEST_NAME, in the background, writing to a log file so heavy output stays out of context.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/telepresenceio/telepresence/blob/HEAD/.claude/skills/integration-tests/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/integration-tests, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
integration-tests
Runs telepresence integration tests from the main conversation. (Replaces the
former integration-test-runner subagent: kept in the main thread so the env
vars and scoping are set here, where this harness's shell-env quirks are known.)
Background to assume
- Tests live under
integration_test/(testify suites) and need a working k8s cluster (kind / minikube / Docker Desktop) plus images it can reach. For a local cluster, setTELEPRESENCE_REGISTRY=localand LOAD images into it (make load-tel2-image, plusmake client-imagefor--docker) rather than pushing to a registry — see Workflow step 2. - Harness is in
integration_test/itest/. Env vars are documented in CLAUDE.md under "Integration Test Environment Variables". itest.yml(next to the telepresenceconfig.yml) pinsTELEPRESENCE_VERSION/TELEPRESENCE_REGISTRYand wins over shell env for the test harness.
Always run via make check-integration
It builds prerequisites and runs go test -json ./integration_test/... | test-report, which renders a live, readable log. Do not hand-roll raw go test.
CRITICAL: pass scoping/config as MAKE ARGUMENTS, not shell env
In this harness, shell exports do NOT persist across separate Bash calls, and
inline VAR=value shell prefixes are disallowed. Pass everything as make
command-line arguments instead — make exports command-line variables into the
recipe's environment, so they reach the go test / test-report process:
make check-integration \
TEST_SUITE='^MySuite$$' \
TEST_LOG_OUTPUT=/tmp/itest-mysuite.log
TEST_SUITE/TEST_NAMEare regexps. Double the trailing$anchor — make eats a single$, so'^MySuite$'becomes^MySuite(anchor lost); use'^MySuite$$'.TEST_SUITEfilters suite names;TEST_NAMEbecomes-testify.m. Combine them to pin one test in one suite.TEST_LOG_OUTPUT→ a FRESH, run-specific path;rm -fit first (it is opened append-mode).test-reportwrites the rendered log here, NOT to stdout.check-integrationbuilds no image (theclient-imageprereq was removed), so it does NOT needTELEPRESENCE_VERSION/TELEPRESENCE_REGISTRY— the test harness reads version/registry fromitest.yml. Pass those vars only to the build/load commands (step 2), matchingitest.yml.
Keep heavy output out of context
This runs in the main thread, so do NOT Read or tail the whole log. Instead:
- Launch the
makecommand withrun_in_background: true. - On completion (or to peek), Read ONLY summary lines from
$TEST_LOG_OUTPUT:grep -E '^(---| ---) (PASS|FAIL|SKIP):' /tmp/itest-mysuite.log(the bare wordFAILalso appears in DEBUG lines — match the--- FAIL:form). The top-level result is--- PASS:/--- FAIL: Test_Integration.
Reading the log
Output streams within seconds once the test phase starts. A persistently empty
$TEST_LOG_OUTPUT after the test phase has begun is a problem (stale lock, wrong
path, or stuck run) — investigate, don't wait it out.
Stale lock / leftover state
If a prior run was killed, before re-running:
telepresence quit -srm -f /tmp/telepresence-itest.lock /tmp/datawire-machine-scoped-default.lock- A leftover traffic-manager ("telepresence-oss ... is already installed in
namespace ") →
helm uninstall traffic-manager -n <ns>and delete the ns.
Workflow
- Identify the suite/test: Grep
integration_test/to map a feature to a suite (<feature>_test.go,SuiteName()) and/or aTest_method. - Decide rebuild. The harness runs the prebuilt host binary plus the
cluster-side images, so rebuild whatever changed. These build/load commands
need
TELEPRESENCE_VERSIONmatchingitest.yml(the image tag isregistry/name:version) and, for a local cluster (kind / minikube / Docker Desktop),TELEPRESENCE_REGISTRY=local— then LOAD images into the cluster instead of pushing to a registry:- client-side Go (
pkg/,cmd/cli):make build TELEPRESENCE_VERSION=<itest.yml>— else the harness runs a stale binary (e.g. missing a newly added flag). - manager/agent (
cmd/traffic,charts/):make load-tel2-image TELEPRESENCE_VERSION=<itest.yml> TELEPRESENCE_REGISTRY=local. --dockertests only:make client-image TELEPRESENCE_VERSION=<itest.yml> TELEPRESENCE_REGISTRY=local(the daemon container runs on the workstation via docker, so it only needs to exist locally — no cluster load).localmakes the harness usepullPolicy=Never. Reservemake push-images(and a realTELEPRESENCE_REGISTRY) for a remote cluster that cannot load local images.
- client-side Go (
- Run scoped (background, fresh
TEST_LOG_OUTPUT). - Summarize: command run, pass/fail/skip counts, failing test names, the smallest log excerpt explaining each failure, and the next concrete action.
Don't
- Don't run the full suite unscoped without explicit user instruction — it is
slow and
-failfastaborts everything on the first failure. - Don't
make clobberor destroy local images without asking. - Don't edit generated files:
docs/reference/cli/**,DEPENDENCIES.md,DEPENDENCY_LICENSES.md,docs/release-notes*.