Testing Intelligent Contracts

The GenLayer Testing Suite (opens in a new tab) (genlayer-test) is a pytest-based framework for testing Intelligent Contracts. It provides two execution modes to match your workflow.

Installation

pip install genlayer-test

Two Modes at a Glance

	Direct Mode	Studio Mode
How it works	Runs contract code in-memory (no network)	Deploys to GenLayer Studio via RPC
Speed	Milliseconds per test	Minutes per test
Prerequisites	Python 3.12+	Python 3.12+ and GenLayer Studio (Docker)
Best for	Unit tests, rapid iteration, CI/CD	Integration tests, consensus validation, testnet
Mocking	`mock_web` / `mock_llm` cheatcodes	Mock validators with LLM/web responses

Start with Direct Mode. It runs in milliseconds, requires no Docker, and covers the vast majority of contract logic. Add Studio Mode tests only when you need multi-validator consensus or full-network behavior.

Direct Mode

Direct Mode runs your contract Python code in-process -- no simulator, no Docker required.

Quick Start

# tests/test_storage.py
 
def test_storage(direct_deploy):
    # Deploy the contract in-memory
    storage = direct_deploy("contracts/Storage.py", "initial value")
 
    # Call view methods directly
    assert storage.get_storage() == "initial value"
 
    # Call write methods directly
    storage.update_storage("updated")
    assert storage.get_storage() == "updated"

Run with pytest:

pytest tests/ -v

Fixtures

Direct Mode provides built-in pytest fixtures:

Fixture	Description
`direct_vm`	VM context with cheatcodes
`direct_deploy`	Deploy a contract in-memory
`direct_alice`, `direct_bob`, `direct_charlie`	Predefined test addresses
`direct_owner`	Default sender address
`direct_accounts`	List of 10 test addresses

Cheatcodes

The direct_vm fixture exposes cheatcodes for controlling test execution:

Changing the Sender

def test_access_control(direct_vm, direct_deploy, direct_alice, direct_bob):
    contract = direct_deploy("contracts/MyContract.py")
 
    # Set sender permanently
    direct_vm.sender = direct_alice
    contract.owner_action()  # Called as alice
 
    # Prank: temporarily change sender for a single call
    with direct_vm.prank(direct_bob):
        with direct_vm.expect_revert("Unauthorized"):
            contract.owner_action()  # Reverts -- bob is not owner

Snapshots and Revert

def test_state_isolation(direct_vm, direct_deploy):
    contract = direct_deploy("contracts/Counter.py")
 
    snap_id = direct_vm.snapshot()
    contract.increment()
    assert contract.get_count() == 1
 
    direct_vm.revert(snap_id)
    assert contract.get_count() == 0  # State fully restored

Snapshots capture full state: storage, mocks, sender, and validators.

Expecting Reverts

def test_insufficient_balance(direct_vm, direct_deploy, direct_alice):
    contract = direct_deploy("contracts/Token.py", direct_alice, 100)
 
    with direct_vm.expect_revert("Insufficient balance"):
        contract.transfer(direct_alice, 999)

Mocking Web and LLM Calls

Non-deterministic calls (gl.nondet.web, gl.nondet.exec_prompt) must be mocked in Direct Mode. Use regex patterns to match URLs and prompt text.

def test_price_feed(direct_vm, direct_deploy):
    # Mock a web response (regex pattern matches the URL)
    direct_vm.mock_web(
        r"api\.example\.com/price",
        {"status": 200, "body": '{"price": 42.50}'}
    )
 
    contract = direct_deploy("contracts/PriceFeed.py")
    contract.update_price()
    assert contract.get_price() == 4250  # Stored as integer

def test_sentiment_analysis(direct_vm, direct_deploy):
    # Mock an LLM response (regex matches the prompt text)
    direct_vm.mock_llm(r"classify.*sentiment", "positive")
 
    contract = direct_deploy("contracts/Sentiment.py")
    contract.analyze("I love GenLayer!")
    assert contract.get_sentiment() == "positive"

⚠️

Set direct_vm.strict_mocks = True to raise an error if any registered mock is never matched. This catches stale or misspelled patterns before they hide bugs.

Testing Validator Consensus

Verify that your equivalence principle produces consistent results across validators:

def test_consensus_agreement(direct_vm, direct_deploy):
    direct_vm.mock_llm(r".*", '{"verdict": "true"}')
 
    contract = direct_deploy("contracts/FactChecker.py")
    # Run as the leader -- captures the validator function internally
    contract.check_claim("The sky is blue")
 
    # Swap mocks to simulate a dissenting validator
    direct_vm.clear_mocks()
    direct_vm.mock_llm(r".*", '{"verdict": "false"}')
    assert direct_vm.run_validator() is False  # Validator disagrees -> undetermined

Studio Mode

Studio Mode deploys your contracts to a running GenLayer Studio instance and interacts via RPC. Use it when you need:

Multi-validator consensus with real network behavior
Verification on localnet or studionet
Pre-testnet integration checks

Prerequisites

GenLayer Studio running locally (genlayer up)
Python 3.12+

Quick Start

from gltest import get_contract_factory
from gltest.assertions import tx_execution_succeeded
 
# `default_account` is a pre-provided pytest fixture supplied by genlayer-test for Studio Mode
def test_contract_integration(default_account):
    factory = get_contract_factory("Storage")
    contract = factory.deploy(args=["initial"])
 
    tx = contract.update_storage(args=["new value"]).transact()
    assert tx_execution_succeeded(tx)
 
    result = contract.get_storage().call()
    assert result == "new value"

Run with the gltest CLI:

gltest tests/ -v
gltest --network studionet
gltest --leader-only   # Skip consensus validation (faster)

For the full Studio Mode API -- mock validators, LLM/web responses, multi-network configuration -- see the genlayer-test API Reference.

Testing Strategy

Structure your test suite in layers:

Pure storage tests first -- verify __init__, view methods, and write methods that do not call gl.nondet. These run instantly and catch most logic bugs.
Mock non-deterministic calls -- add mock_web / mock_llm to test the full execution flow with controlled outputs. Cover both happy paths and edge cases (empty responses, unexpected LLM output, HTTP errors).
Consensus tests -- use direct_vm.run_validator() to confirm your equivalence principle produces agreement on typical inputs. Also verify that validators disagree on inputs designed to be ambiguous.
Studio Mode last -- run a smaller set of integration tests against localnet in CI to verify end-to-end behavior with real validators.

Enable direct_vm.check_pickling = True to catch serialization bugs early. GenLayer stores contract state by pickling Python objects -- any custom class not decorated with @allow_storage and @dataclass will fail at runtime.

Debugging Deploying