// Architecture and agent rules for kurtosis-cdk E2E tests. Load when working on or debugging E2E tests, CI failures in the e2e job, or any task involving bridge testing or kurtosis.
| name | tech-e2e-tests |
| description | Architecture and agent rules for kurtosis-cdk E2E tests. Load when working on or debugging E2E tests, CI failures in the e2e job, or any task involving bridge testing or kurtosis. |
The CI workflow .github/workflows/test.yml
(job call-agglayer-node-e2e-workflow) calls an external reusable workflow at
agglayer/e2e/.github/workflows/agglayer-node-e2e.yml.
It passes:
docker-image-override: agglayer_image)kurtosis-cdk-ref commitagglayer-e2e-ref commitkurtosis-cdk-args JSON block configuring the network
(including l1_el_type, sequencer_type, and reth_image
for the reth-based L1)The workflow runs
bats tests/agglayer/bridges.bats tests/agglayer/rpc-tests.bats --filter-tags agglayer
in the agglayer/e2e repo.
The bridges.bats file covers L1/L2 bridging;
rpc-tests.bats validates reth-specific RPC methods
(e.g. eth_getTransactionBySenderAndNonce).
E2E jobs only trigger on merge_group and workflow_dispatch events,
not on pull_request.
See Validating E2E on a PR branch
for how to exercise them before merging.
The agglayer/e2e repo bundles its own bats-support/bats-assert libraries
in core/helpers/lib/.
The tests use polycli ulxly bridge asset and polycli ulxly claim asset
for bridge operations.
The test environment is bootstrapped by sourcing tests/.env and
core/helpers/common.bash (_setup_vars), which auto-discovers RPC URLs,
bridge addresses, and private keys from the running kurtosis enclave.
All pinned commits and args live in .github/workflows/test.yml;
that is the single source of truth.
Always ask whether to rebuild agglayer:local before running.
Recommend rebuilding (docker build -t agglayer:local . from the repo root)
because skipping means the tests run against a stale image
that does not reflect the current code.
polycli version must match CI.
The reusable workflow agglayer/e2e/.github/workflows/agglayer-node-e2e.yml
pins POLYCLI_VERSION (e.g. v0.1.90) as an env var near the top.
Install the matching release binary rather than building from source,
because make install produces the latest dev build which may have
regressions (e.g. gas estimation changes that cause bridge tx reverts).
To install a specific version:
curl -sL "https://github.com/0xPolygon/polygon-cli/releases/download/${POLYCLI_VERSION}/polycli_${POLYCLI_VERSION}_linux_amd64.tar.gz" \
| tar xz -C ~/go/bin/ && mv ~/go/bin/polycli_* ~/go/bin/polycli
polycli lives at ~/go/bin/polycli and is not on the default PATH.
Export PATH="$PATH:$HOME/go/bin" before running bats or any polycli commands.
External repos are cached under /tmp/agglayer-e2e/.
Before cloning, check whether they already exist at the correct refs
(compare git -C <dir> rev-parse HEAD with the pinned SHA in
.github/workflows/test.yml).
Re-clone only if the ref has changed.
The kurtosis args file at /tmp/agglayer-e2e/kurtosis-args.json
should be checked/regenerated from test.yml each run
(ensure "agglayer_image": "agglayer:local" is present in args).
When e2e tests fail locally but pass in CI, check tool versions first.
Compare local versions of polycli, kurtosis, bats, and foundry/cast
against the versions CI installs (defined in agglayer-node-e2e.yml).
Version drift is a common root cause of otherwise-mysterious failures
(e.g. gas estimation regressions, changed CLI flags).
For step-by-step local setup, see docs/knowledge-base/e2e-tests.md.
E2E jobs only run on merge_group and workflow_dispatch events,
so they are skipped during normal PR CI.
To exercise them before the PR enters the merge queue,
trigger a workflow_dispatch run against the PR branch:
gh workflow run test.yml --repo agglayer/agglayer --ref <branch-name>
Monitor the run with:
gh run list --repo agglayer/agglayer --branch <branch-name> --workflow test.yml --limit 1
gh run view <run-id> --repo agglayer/agglayer --json jobs \
--jq '.jobs[] | "\(.name)\t\(.conclusion)"'
This run includes the full E2E suite (docker build + kurtosis + bats tests) and typically takes ~30 minutes.
Create a git commit following project conventions.
Create a pull request following project conventions.
**Mandatory** before any commit or push. Run Definition-of-Done checks from change scope and report exact pass/fail per command.
Review the current conversation and propose structured improvements to skills, documentation, and agent rules.
Create or update docs/knowledge-base/ chapters in mdbook format for human-first technical documentation.
Text formatting conventions for markdown and prose files. Use when writing or editing any .md, .txt, .adoc, or .rst file, including AGENTS.md, SKILL.md files, and documentation in docs/.