Run E2e

swctl, yq, and other tools

E2E test cases run pre-install steps (see setup.steps in each e2e.yaml) that install tools into /tmp/skywalking-infra-e2e/bin. When running locally, you need these tools on your PATH.

swctl — SkyWalking CLI, used in verify cases to query OAP's GraphQL API. Pinned at SW_CTL_COMMIT in test/e2e-v2/script/env:

# Option 1: Use the install script (same as CI)
bash test/e2e-v2/script/prepare/setup-e2e-shell/install.sh swctl
export PATH=/tmp/skywalking-infra-e2e/bin:$PATH

# Option 2: Build from source
go install github.com/apache/skywalking-cli/cmd/swctl@<SW_CTL_COMMIT>

yq — YAML processor, used in verify cases:

# Option 1: Use the install script
bash test/e2e-v2/script/prepare/setup-e2e-shell/install.sh yq
export PATH=/tmp/skywalking-infra-e2e/bin:$PATH

# Option 2: brew install yq (macOS)

Other tools (only needed for specific test cases):

All install scripts are at test/e2e-v2/script/prepare/setup-e2e-shell/.

Steps

1. Determine the test case

Resolve the user's argument to a full path under test/e2e-v2/cases/. If ambiguous, list matching directories and ask.

ls test/e2e-v2/cases/<argument>/e2e.yaml

2. Check if rebuild is needed

Compare source file timestamps against the last build:

# OAP server changes since last build
find oap-server apm-protocol -type f \( \
  -name "*.java" -o -name "*.yaml" -o -name "*.yml" -o \
  -name "*.json" -o -name "*.xml" -o -name "*.properties" -o \
  -name "*.proto" \
\) -newer dist/apache-skywalking-apm-bin.tar.gz 2>/dev/null | head -5

# Test service changes since last build
find test/e2e-v2/java-test-service -type f \( \
  -name "*.java" -o -name "*.xml" -o -name "*.yaml" -o -name "*.yml" \
\) -newer test/e2e-v2/java-test-service/e2e-service-provider/target/*.jar 2>/dev/null | head -5

If files are found, warn the user and suggest rebuilding before running.

3. Rebuild if needed (only with user confirmation)

# Rebuild OAP
./mvnw clean flatten:flatten package -Pall -Dmaven.test.skip && make docker

# Rebuild test services
./mvnw -f test/e2e-v2/java-test-service/pom.xml clean flatten:flatten package

4. Run the E2E test

Set required environment variables and run:

export SW_AGENT_JDK_VERSION=8
e2e run -c test/e2e-v2/cases/<case-path>/e2e.yaml

5. If the test fails

Do NOT run cleanup immediately. Instead:

1. Check container logs:

   docker compose -f test/e2e-v2/cases/<case-path>/docker-compose.yml logs oap
   docker compose -f test/e2e-v2/cases/<case-path>/docker-compose.yml logs provider
   

2. Run verify separately (can retry after investigation):

   e2e verify -c test/e2e-v2/cases/<case-path>/e2e.yaml
   

3. Only cleanup when done debugging:

   e2e cleanup -c test/e2e-v2/cases/<case-path>/e2e.yaml
   

Common test cases