Integration Tests

Run contracts against a real GenLayer environment (GLSim, Studio, or testnet) with full consensus validation.

Running Tests

# Against default network (from gltest.config.yaml)
gltest tests/integration/ -v -s

# Against specific network
gltest tests/integration/ -v -s --network localnet
gltest tests/integration/ -v -s --network studionet
gltest tests/integration/ -v -s --network testnet_bradbury

Always use -v -s for visible output during development.

Test Pattern

from gltest import get_contract_factory
from gltest.assertions import tx_execution_succeeded

def test_full_flow():
    factory = get_contract_factory("MyContract")
    contract = factory.deploy(args=[])

    # Write methods return transaction receipts
    tx_receipt = contract.set_data(args=["hello"]).transact()
    assert tx_execution_succeeded(tx_receipt)

    # Read methods return values directly
    result = contract.get_data(args=[contract.address]).call()
    assert result == "hello"

ACCEPTED and FINALIZED are transaction lifecycle states, not proof that contract execution succeeded. A transaction can be accepted and finalized with an execution error, and failed execution applies no state changes. For deploy transactions, failed execution means no contract is created.

Always assert tx_execution_succeeded(receipt) before reading state, checking schema/code, or treating a missing contract as an infrastructure issue.

Key Differences from Direct Mode

	Direct Mode	Integration Tests
Speed	~30ms	~seconds to minutes
Server required	No	Yes (GLSim, Studio, or testnet)
Consensus	Leader only	Full leader + validators
Write methods	Return values directly	Return transaction receipts
Read methods	Return values directly	Use .call()
Mocking	mock_web() / mock_llm()	Real web/LLM calls

Write vs Read Calls

Write methods (state-changing):

# .transact() submits and waits for consensus
tx_receipt = contract.method_name(args=[arg1, arg2]).transact()
assert tx_execution_succeeded(tx_receipt)

Read methods (view-only):

# .call() reads without transaction
result = contract.view_method(args=[arg1]).call()

Configuration (gltest.config.yaml)

contract_path: contracts/

networks:
  localnet:
    # GenLayer Studio running locally
  studionet:
    # studio.genlayer.com — gasless, no funding needed (0 GEN balance is fine)
  testnet_bradbury:
    accounts:
      - "${ACCOUNT_PRIVATE_KEY_1}"
      - "${ACCOUNT_PRIVATE_KEY_2}"

Test Markers

import pytest

@pytest.mark.slow
def test_expensive_operation():
    """Excluded by default. Run with: gltest -m slow"""
    pass

Environments

• GLSim (pip install genlayer-test[sim], glsim --port 4000 --validators 5) — lightweight, no Docker, ~1s startup. Runs Python natively, not in GenVM. Good for fast iteration.
• Studio local (genlayer up) — full GenVM, real consensus, Docker required. Validates runtime compatibility.
• studio.genlayer.com (StudioNet) — hosted Studio, no setup, rate-limited (see Common Issues). Gasless: no tokens required. Accounts with 0 GEN balance can deploy and run tests normally.
• Testnet Bradbury — real network, requires funded accounts.

When to Use Integration Tests

• Validating consensus (leader + validators agree)
• Testing real web requests and LLM calls
• Pre-deployment smoke tests
• Verifying contract works in actual GenVM (not just Python runner)

Direct mode should cover most logic testing. Use integration tests for final validation before deploying.

Common Issues

"Transaction not found" errors

Clear cache: rm -rf .gltest_cache

Slow tests

Run single tests during development:

gltest tests/integration/test_file.py::test_specific -v -s

JSON serialization

When working with mock validators, convert to dicts:

transaction_context = {"validators": [v.to_dict() for v in mock_validators]}

Studio rate limits (HTTP 429 / -32429)

studio.genlayer.com enforces per-IP limits: 60 req/min, 1000 req/hr, 10000 req/day. Limits aren't permanent — once tripped, further requests are rejected until the current window resets (next minute / hour / day cycle). Throttle batch tests, run heavy suites against localnet (GLSim or local Studio), or pace .transact() calls.

-32028 is the related pending-queue cap — up to 32 in-flight txs per sender; a separate cap also applies per contract to prevent flooding the shared Studio. Wait for receipts before submitting the next batch instead of firing in parallel.