Cheatcodes
Most of the time, testing smart contracts with assertions only is not enough. Some test cases require manipulating the state of the blockchain, as well as checking for reverts and events. For that reason, Protostar provides a set of cheatcodes.
Cheatcodes are available inside of Cairo hints. You don't have to import anything. When Protostar runs tests, it replaces some core elements in cairo-lang library and injects cheatcodes to the hint scope.
If you are familiar with Foundry, you will recognize most cheatcodes.
Available cheatcodes
📄️ assume
assume(condition) skips testing against the given example if the condition is False.
📄️ declare
Declares contract given a path relative to a Protostar project root.
📄️ deploy_contract
Deploys a contract given a path relative to a Protostar project root. The section Deploying contracts from tests demonstrates a usage of this cheatcode.
📄️ deploy
Deploys contract for deployment given PreparedContract.
📄️ example
Parametrizes test with explicitly provided data.
📄️ expect_call
Allows specifying what calls to contracts' functions are expected in the code.
📄️ expect_events
Compares expected events with events in the Starknet state. You can use this cheatcode to test whether a contract emits specified events. Protostar compares events after a test case is completed. Therefore, you can use this cheatcode in any place within a test case.
📄️ expect_revert
If a code beneath expect_revert raises a specified exception, a test will pass. If not, a test will fail.
📄️ given
Instructs the fuzzer to adopt a specific fuzzing strategy for input parameters.
📄️ load
Loads storage variable with name variablename and given key and variabletype from a contract with targetcontractaddress.
📄️ max_examples
Set the maximum number of examples to explore by the fuzzer.
📄️ mock_call
Mocks all calls to function with the name fnname of a contract with an address contractaddress, until the returned callable is called.
📄️ prepare
Prepares contract for deployment given DeclaredContract and constructor_calldata. The cheatcode is useful when you want to know contract address before deploying it to affect constructor with a targeted cheatcode. Example:
📄️ reflect
Loads specified a Cairo object into a Python type. reflect is a function that takes in ids and returns Reflector object that behaves simillarly. To retrieve the value use get() method which can return:
📄️ reject
reject() skips testing against the given example.
📄️ roll
Changes a block number until the returned function is called. If targetcontractaddress is specified, roll affects only the contract with the specified address. Otherwise, roll affects the current contract.
📄️ send_message_to_l2
This cheatcode simulates an incoming message from L1 to L2 executed with fnname at toaddress contract address.
📄️ skip
Skip a test. You can use this cheatcode to prepare tests for functionality that isn't completed yet.
📄️ start_prank
Changes a caller address returned by getcalleraddress() until the returned callable is called. If targetcontractaddress is specified, startprank affects only the contract with the specified address. Otherwise, startprank affects the current contract.
📄️ store
Updates storage variable with name variablename and given key to value of a contract with targetcontract_address.
📄️ strategy
A [Python namespace] containing constructors of built-in fuzzing strategies.
📄️ warp
Changes a block timestamp until the returned function is called. If targetcontractaddress is specified, warp affects only the contract with the specified address. Otherwise, warp affects the current contract.
Data Transformer
What is a Data Transformer
Data Transformer converts inputs and outputs of Cairo functions to Python friendly representation. Cairo internally operates on a list of integers, which readability and maintenance become problematic for complex data structures. You can read more about:
- Data Transformer in the Starknet.py's documentation.
- representing tuples and structs as a list of integers in the official documentation
Using Data Transformer in cheatcodes
Cheatcodes accept arguments representing input or output of a Cairo function as:
List[int]
— a list of integersDict[DataTransformer.ArgumentName, DataTransformer.SupportedType]
— Data Transformer friendly dictionary
Example
The following example demonstrates usage on the deploy_contract
.
%lang starknet
from starkware.cairo.common.uint256 import Uint256
@constructor
func constructor(initial_balance: Uint256, contract_id: felt) {
// ...
return ();
}
deploy_contract("./src/main.cairo", { "initial_balance": 42, "contract_id": 123 })
deploy_contract("./src/main.cairo", [42, 0, 123])