Integration tests for ZKsync OS. Spins up a full ecosystem — Anvil L1, deployed
contracts, in-process zksync-os-server per chain — and runs end-to-end tests
against it. No Docker required.
- Rust nightly-2026-01-22 (pinned in
rust-toolchain.toml) - Foundry (
anvil,forge,cast) - Yarn (forge deployment scripts call node helpers via FFI)
# Run the full integration suite (release strongly recommended — debug-build
# servers are too slow for the test timeouts)
cargo test -p tests --release
# Run a single test
cargo test -p tests --release --test l1 chain_executes_a_batchContracts are compiled automatically on first use (forge build inside the
era-contracts checkout that the protocol_ops dependency pins).
.
├── bin/zk-deployer/ # Deployment engine + CLI: intent.yaml → bootstrap → apply
├── lib/server/ # In-process zksync-os-server wrapper + RPC wait helpers
├── tests/ # Test framework (rstest fixtures) + integration tests
│ ├── src/fixtures/ # ecosystem (N L1-settling chains), v30_chain (frozen fixture)
│ ├── tests/ # l1.rs, upgrade_v30_to_v31.rs
│ └── local-chains/ # committed v30.2 frozen state for upgrade tests
└── .zkos-test-cache/ # Deployment snapshot cache (gitignored)
See tests/README.md for the test-framework API and bin/zk-deployer/README.md
for the standalone CLI.
era-contracts (via the protocol_ops library crate) and zksync-os-server
are git dependencies in Cargo.toml; the exact revisions are pinned by
Cargo.lock. To test against a different revision:
cargo update -p protocol_ops # or: --precise <rev>
cargo update -p zksync_os_server-
Uncomment the
[patch."https://github.com/matter-labs/era-contracts"]block inCargo.tomland point it at your local checkout. -
Set
PROTOCOL_CONTRACTS_ROOTto the same path:export PROTOCOL_CONTRACTS_ROOT=../era-contracts cargo test -p tests --release
Without
PROTOCOL_CONTRACTS_ROOTthe deployment cache keys on the git rev and ignores local Solidity edits — the env var switches it to a content hash so any edit correctly invalidates the cached deployment.
Uncomment the [patch."https://github.com/matter-labs/zksync-os-server"] block
in Cargo.toml and point it at your local checkout. No env var needed — server
code is deliberately excluded from the cache key, so local server builds still
get cache hits on the deployment half (contracts, wallet deposits) and only pay
for the server recompile.
Same pattern: uncomment the [patch."https://github.com/matter-labs/zksync-os"]
block and fill in the crate paths within your local checkout.
Tests are Rust integration tests in tests/tests/, using rstest fixtures:
use rstest::rstest;
use tests::fixtures::ecosystem;
use tests::Ecosystem;
#[rstest]
#[tokio::test(flavor = "multi_thread")]
async fn my_test(#[future] ecosystem: Ecosystem) {
let eco = ecosystem.await;
eco.chain().ping().await;
eco.chain().wait_for_batch().await;
}Multi-chain topologies are declared at the call site:
#[with(vec![6565, 6566])] ecosystem: EcosystemFull API reference: tests/README.md, including environment variables for debugging
(ZKOS_TEST_DIR, ZKOS_CACHE, RUST_LOG).
See CONTRIBUTING.md for contribution guidelines.
See SECURITY.md for security policy details.
ZKsync OS repositories are distributed under the terms of either
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/blog/license/mit/)
at your option.