251 lines
8.3 KiB
Markdown
251 lines
8.3 KiB
Markdown
# Forge Standard Library • [](https://github.com/foundry-rs/forge-std/actions/workflows/ci.yml)
|
|
|
|
Forge Standard Library is a collection of helpful contracts and libraries for use with [Forge and Foundry](https://github.com/foundry-rs/foundry). It leverages Forge's cheatcodes to make writing tests easier and faster, while improving the UX of cheatcodes.
|
|
|
|
**Learn how to use Forge-Std with the [📖 Foundry Book (Forge-Std Guide)](https://book.getfoundry.sh/forge/forge-std.html).**
|
|
|
|
## Install
|
|
|
|
```bash
|
|
forge install foundry-rs/forge-std
|
|
```
|
|
|
|
## Contracts
|
|
### stdError
|
|
|
|
This is a helper contract for errors and reverts. In Forge, this contract is particularly helpful for the `expectRevert` cheatcode, as it provides all compiler builtin errors.
|
|
|
|
See the contract itself for all error codes.
|
|
|
|
#### Example usage
|
|
|
|
```solidity
|
|
|
|
import "forge-std/Test.sol";
|
|
|
|
contract TestContract is Test {
|
|
ErrorsTest test;
|
|
|
|
function setUp() public {
|
|
test = new ErrorsTest();
|
|
}
|
|
|
|
function testExpectArithmetic() public {
|
|
vm.expectRevert(stdError.arithmeticError);
|
|
test.arithmeticError(10);
|
|
}
|
|
}
|
|
|
|
contract ErrorsTest {
|
|
function arithmeticError(uint256 a) public {
|
|
uint256 a = a - 100;
|
|
}
|
|
}
|
|
```
|
|
|
|
### stdStorage
|
|
|
|
This is a rather large contract due to all of the overloading to make the UX decent. Primarily, it is a wrapper around the `record` and `accesses` cheatcodes. It can *always* find and write the storage slot(s) associated with a particular variable without knowing the storage layout. The one _major_ caveat to this is while a slot can be found for packed storage variables, we can't write to that variable safely. If a user tries to write to a packed slot, the execution throws an error, unless it is uninitialized (`bytes32(0)`).
|
|
|
|
This works by recording all `SLOAD`s and `SSTORE`s during a function call. If there is a single slot read or written to, it immediately returns the slot. Otherwise, behind the scenes, we iterate through and check each one (assuming the user passed in a `depth` parameter). If the variable is a struct, you can pass in a `depth` parameter which is basically the field depth.
|
|
|
|
I.e.:
|
|
```solidity
|
|
struct T {
|
|
// depth 0
|
|
uint256 a;
|
|
// depth 1
|
|
uint256 b;
|
|
}
|
|
```
|
|
|
|
#### Example usage
|
|
|
|
```solidity
|
|
import "forge-std/Test.sol";
|
|
|
|
contract TestContract is Test {
|
|
using stdStorage for StdStorage;
|
|
|
|
Storage test;
|
|
|
|
function setUp() public {
|
|
test = new Storage();
|
|
}
|
|
|
|
function testFindExists() public {
|
|
// Lets say we want to find the slot for the public
|
|
// variable `exists`. We just pass in the function selector
|
|
// to the `find` command
|
|
uint256 slot = stdstore.target(address(test)).sig("exists()").find();
|
|
assertEq(slot, 0);
|
|
}
|
|
|
|
function testWriteExists() public {
|
|
// Lets say we want to write to the slot for the public
|
|
// variable `exists`. We just pass in the function selector
|
|
// to the `checked_write` command
|
|
stdstore.target(address(test)).sig("exists()").checked_write(100);
|
|
assertEq(test.exists(), 100);
|
|
}
|
|
|
|
// It supports arbitrary storage layouts, like assembly based storage locations
|
|
function testFindHidden() public {
|
|
// `hidden` is a random hash of a bytes, iteration through slots would
|
|
// not find it. Our mechanism does
|
|
// Also, you can use the selector instead of a string
|
|
uint256 slot = stdstore.target(address(test)).sig(test.hidden.selector).find();
|
|
assertEq(slot, uint256(keccak256("my.random.var")));
|
|
}
|
|
|
|
// If targeting a mapping, you have to pass in the keys necessary to perform the find
|
|
// i.e.:
|
|
function testFindMapping() public {
|
|
uint256 slot = stdstore
|
|
.target(address(test))
|
|
.sig(test.map_addr.selector)
|
|
.with_key(address(this))
|
|
.find();
|
|
// in the `Storage` constructor, we wrote that this address' value was 1 in the map
|
|
// so when we load the slot, we expect it to be 1
|
|
assertEq(uint(vm.load(address(test), bytes32(slot))), 1);
|
|
}
|
|
|
|
// If the target is a struct, you can specify the field depth:
|
|
function testFindStruct() public {
|
|
// NOTE: see the depth parameter - 0 means 0th field, 1 means 1st field, etc.
|
|
uint256 slot_for_a_field = stdstore
|
|
.target(address(test))
|
|
.sig(test.basicStruct.selector)
|
|
.depth(0)
|
|
.find();
|
|
|
|
uint256 slot_for_b_field = stdstore
|
|
.target(address(test))
|
|
.sig(test.basicStruct.selector)
|
|
.depth(1)
|
|
.find();
|
|
|
|
assertEq(uint(vm.load(address(test), bytes32(slot_for_a_field))), 1);
|
|
assertEq(uint(vm.load(address(test), bytes32(slot_for_b_field))), 2);
|
|
}
|
|
}
|
|
|
|
// A complex storage contract
|
|
contract Storage {
|
|
struct UnpackedStruct {
|
|
uint256 a;
|
|
uint256 b;
|
|
}
|
|
|
|
constructor() {
|
|
map_addr[msg.sender] = 1;
|
|
}
|
|
|
|
uint256 public exists = 1;
|
|
mapping(address => uint256) public map_addr;
|
|
// mapping(address => Packed) public map_packed;
|
|
mapping(address => UnpackedStruct) public map_struct;
|
|
mapping(address => mapping(address => uint256)) public deep_map;
|
|
mapping(address => mapping(address => UnpackedStruct)) public deep_map_struct;
|
|
UnpackedStruct public basicStruct = UnpackedStruct({
|
|
a: 1,
|
|
b: 2
|
|
});
|
|
|
|
function hidden() public view returns (bytes32 t) {
|
|
// an extremely hidden storage slot
|
|
bytes32 slot = keccak256("my.random.var");
|
|
assembly {
|
|
t := sload(slot)
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### stdCheats
|
|
|
|
This is a wrapper over miscellaneous cheatcodes that need wrappers to be more dev friendly. Currently there are only functions related to `prank`. In general, users may expect ETH to be put into an address on `prank`, but this is not the case for safety reasons. Explicitly this `hoax` function should only be used for address that have expected balances as it will get overwritten. If an address already has ETH, you should just use `prank`. If you want to change that balance explicitly, just use `deal`. If you want to do both, `hoax` is also right for you.
|
|
|
|
|
|
#### Example usage:
|
|
```solidity
|
|
|
|
// SPDX-License-Identifier: MIT
|
|
pragma solidity ^0.8.0;
|
|
|
|
import "forge-std/Test.sol";
|
|
|
|
// Inherit the stdCheats
|
|
contract StdCheatsTest is Test {
|
|
Bar test;
|
|
function setUp() public {
|
|
test = new Bar();
|
|
}
|
|
|
|
function testHoax() public {
|
|
// we call `hoax`, which gives the target address
|
|
// eth and then calls `prank`
|
|
hoax(address(1337));
|
|
test.bar{value: 100}(address(1337));
|
|
|
|
// overloaded to allow you to specify how much eth to
|
|
// initialize the address with
|
|
hoax(address(1337), 1);
|
|
test.bar{value: 1}(address(1337));
|
|
}
|
|
|
|
function testStartHoax() public {
|
|
// we call `startHoax`, which gives the target address
|
|
// eth and then calls `startPrank`
|
|
//
|
|
// it is also overloaded so that you can specify an eth amount
|
|
startHoax(address(1337));
|
|
test.bar{value: 100}(address(1337));
|
|
test.bar{value: 100}(address(1337));
|
|
vm.stopPrank();
|
|
test.bar(address(this));
|
|
}
|
|
}
|
|
|
|
contract Bar {
|
|
function bar(address expectedSender) public payable {
|
|
require(msg.sender == expectedSender, "!prank");
|
|
}
|
|
}
|
|
```
|
|
|
|
### Std Assertions
|
|
|
|
Expand upon the assertion functions from the `DSTest` library.
|
|
|
|
### `console.log`
|
|
|
|
Usage follows the same format as [Hardhat](https://hardhat.org/hardhat-network/reference/#console-log).
|
|
It's recommended to use `console2.sol` as shown below, as this will show the decoded logs in Forge traces.
|
|
|
|
```solidity
|
|
// import it indirectly via Test.sol
|
|
import "forge-std/Test.sol";
|
|
// or directly import it
|
|
import "forge-std/console2.sol";
|
|
...
|
|
console2.log(someValue);
|
|
```
|
|
|
|
If you need compatibility with Hardhat, you must use the standard `console.sol` instead.
|
|
Due to a bug in `console.sol`, logs that use `uint256` or `int256` types will not be properly decoded in Forge traces.
|
|
|
|
```solidity
|
|
// import it indirectly via Test.sol
|
|
import "forge-std/Test.sol";
|
|
// or directly import it
|
|
import "forge-std/console.sol";
|
|
...
|
|
console.log(someValue);
|
|
```
|
|
|
|
## License
|
|
|
|
Forge Standard Library is offered under either [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE) license.
|