Skip to content
This repository has been archived by the owner on Jun 20, 2024. It is now read-only.

Commit

Permalink
Merge branch 'main' into fix-scarb_toml-OZ-cario-contract-dependency
Browse files Browse the repository at this point in the history
  • Loading branch information
@omarespejel
omarespejel authored Oct 19, 2023
2 parents fb3ce1d + 5f81c62 commit 9f87efa
Showing 1 changed file with 62 additions and 121 deletions.
183 changes: 62 additions & 121 deletions src/ch02-11-foundry-forge.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,34 +13,39 @@ Merely deploying contracts is not the end game. Many tools have offered this cap

To utilize Forge, define test functions and label them with test attributes. Users can either test standalone Cairo functions or integrate contracts, dispatchers, and test contract interactions on-chain.

## Using `snForge` command-line
## `snForge` Command-Line Usage

This section provides an introduction to the Starknet Foundry `snforge` command-line tool. We will walk you through the process of creating a new project, compiling your code, and running tests.
This section guides you through the Starknet Foundry `snforge` command-line tool. Learn how to set up a new project, compile the code, and execute tests.

## Creating a New Project

To initiate a new project using Starknet Foundry, you can use the `--init` command. Replace `project_name` with the desired name for your project.
To start a new project with Starknet Foundry, use the `--init` command and replace `project_name` with your project's name.

```shell
snforge --init project_name
```

After creating the project, you can explore its structure as follows:
Once you've set up the project, inspect its layout:

```shell
cd project_name
tree . -L 1
```

The project structure is as follows:


```shell
$ cd project_name
$ tree . -L 1
.
├── README.md
├── Scarb.toml
├── src
└── tests
```

- src/ contains the source code for all your contracts.
- tests/ is where your test files are located.
- Scarb.toml contains the project and `snforge` configuration.
Make sure that the casm code generation is enabled in the Scarb.toml file:
- `src/` holds your contract source code.
- `tests/` is the location of your test files.
- `Scarb.toml` is for project and **`snforge`** configurations.

Ensure the casm code generation is active in the `Scarb.toml` file:

```shell
# ...
Expand All @@ -49,10 +54,11 @@ casm = true
# ...
```

Now, you can run tests with `snforge`:
To run tests using `snforge`:

```shell
$ snforge
snforge

Collected 2 test(s) from the `test_name` package
Running 0 test(s) from `src/`
Running 2 test(s) from `tests/`
Expand All @@ -61,44 +67,43 @@ Running 2 test(s) from `tests/`
Tests: 2 passed, 0 failed, 0 skipped
```

## Using snforge with Existing Scarb Projects
## Integrating `snforge` with Existing Scarb Projects

If you have an existing Scarb project and want to use `snforge`, ensure that you have declared the `snforge_std package` as a dependency in your project. Add the following line under the [dependencies] section in your Scarb.toml file:
For those with an established Scarb project who wish to incorporate `snforge`, ensure the `snforge_std package` is declared as a dependency. Insert the line below in the [dependencies] section of your `Scarb.toml`:

```shell
# ...
[dependencies]
snforge_std = { git = "https://github.com/foundry-rs/starknet-foundry.git", tag = "v0.7.1" }
snforge_std = { git = "https://github.com/foundry-rs/starknet-foundry.git", tag = "[VERSION]" }
```
Make sure that the version in the tag matches the version of snforge. You can check the installed snforge version with the following command:
Ensure the tag version corresponds with your `snforge` version. To verify your `snforge` version:
```shell
$ snforge --version
forge 0.7.1
```sh
snforge --version
```
Alternatively, you can add this dependency using the `scarb` command:
Or, add this dependency using the `scarb` command:
```shell
$ scarb add snforge_std --git https://github.com/foundry-rs/starknet-foundry.git --tag v0.7.1
scarb add snforge_std --git https://github.com/foundry-rs/starknet-foundry.git --tag VERSION
```
Now, you are ready to use `snforge` with your existing Scarb project.
With these steps, your existing Scarb project is now **`snforge`**-ready.
## Running Tests with snforge
## Testing with `snforge`
To run tests using the Starknet Foundry `snforge` command, follow these instructions. We will cover `test execution`, `test filtering`, `running specific tests`, and `handling test execution failures`.
Utilize Starknet Foundry's `snforge` command to efficiently run tests.
### Running Tests
### Executing Tests
To execute tests, navigate to the package directory and run the following command:
Navigate to the package directory and issue this command to run tests:
```shell
$ snforge
snforge
```
This command collects and runs tests within the specified package. Here's an example output:
Sample output might resemble:
```shell
Collected 3 test(s) from `package_name` package
Expand All @@ -109,61 +114,37 @@ Running 3 test(s) from `src/`
Tests: 3 passed, 0 failed, 0 skipped
```
### Filtering Tests
### Filter Tests
Run specific tests using a filter string after the `snforge` command. Tests matching the filter based on their absolute module tree path will be executed:
You can filter the tests to run by passing a filter string after the `snforge` command. By default, tests with an absolute module tree path matching the filter will be executed:
```shell
$ snforge calling
Collected 2 test(s) from `package_name` package
Running 2 test(s) from `src/`
[PASS] package_name::calling
[PASS] package_name::calling_another
Tests: 2 passed, 0 failed, 0 skipped
```
### Running a Specific Test
### Run a Specific Test
To run a specific test, you can use the `--exact` flag along with the filter string. Ensure that you use a fully qualified test name, including the module name:
Use the `--exact` flag and a fully qualified test name to run a particular test:
```shell
$ snforge package_name::calling --exact
Collected 1 test(s) from `package_name` package
Running 1 test(s) from `src/`
[PASS] package_name::calling
Tests: 1 passed, 0 failed, 0 skipped
```shell
snforge package_name::calling --exact
```
### Stopping Test Execution After First Failed Test
### Stop After First Test Failure
To halt test execution after the first failed test, include the `--exit-first` flag with the `snforge` command:
To stop after the first test failure, add the `--exit-first` flag to the `snforge` command:
```shell
$ snforge --exit-first
Collected 6 test(s) from package_name package
Running 6 test(s) from src/
[PASS] package_name::executing
[PASS] package_name::calling
[PASS] package_name::calling_another
[FAIL] package_name::failing
Failure data:
original value: [8111420071579136082810415440747], converted to a string: [failing check]
[SKIP] package_name::other_test
[SKIP] package_name::yet_another_test
Tests: 3 passed, 1 failed, 2 skipped
Failures:
package_name::failing
snforge --exit-first
```
## Testing Starknet contract with `snforge` (Example)
## Basic Example
In this example we'll be using the below starknet contract:
The example provided below demonstrates how to test a Starknet contract using `snforge`.
```shell
```rust
#[starknet::interface]
trait IHelloStarknet<TContractState> {
fn increase_balance(ref self: TContractState, amount: felt252);
Expand All @@ -179,96 +160,56 @@ mod HelloStarknet {
#[external(v0)]
impl HelloStarknetImpl of super::IHelloStarknet<ContractState> {
// Increases the balance by the given amount.
// Increases the balance by the specified amount.
fn increase_balance(ref self: ContractState, amount: felt252) {
self.balance.write(self.balance.read() + amount);
}
// Gets the balance.
// Returns the balance.
fn get_balance(self: @ContractState) -> felt252 {
self.balance.read()
}
}
}
```
It should be noted that the name written after `mod` is the contract name which would be referenced later on; in this case, it is `HelloStarknet`.
Remember, the identifier following `mod` signifies the contract name. Here, the contract name is `HelloStarknet`.
## Writing the test
### Craft the Test
let's write the test cases for `HelloStarknet` contract. In this test, we'll deploy `Hellostarknet` and interact with some functions:
Below is a test for the **`HelloStarknet`** contract. This test deploys **`HelloStarknet`** and interacts with its functions:
```shell
```rust
use snforge_std::{ declare, ContractClassTrait };
#[test]
fn call_and_invoke() {
// First declare and deploy a contract
// Declare and deploy the contract
let contract = declare('HelloStarknet');
let contract_address = contract.deploy(@ArrayTrait::new()).unwrap();
// Create a Dispatcher object that will allow interacting with the deployed contract
// Instantiate a Dispatcher object for contract interactions
let dispatcher = IHelloStarknetDispatcher { contract_address };
// Call a view function of the contract
// Invoke a contract's view function
let balance = dispatcher.get_balance();
assert(balance == 0, 'balance == 0');
// Call a function of the contract
// Here we mutate the state of the storage
// Invoke another function to modify the storage state
dispatcher.increase_balance(100);
// Check that transaction took effect
// Validate the transaction's effect
let balance = dispatcher.get_balance();
assert(balance == 100, 'balance == 100');
}
```
Now we are ready to run `snforge`. once you run the `snforge` command, you should get the below output
To run the test, execute the `snforge` command. The expected output is:
```shell
$ snforge
Collected 1 test(s) from using_dispatchers package
Running 1 test(s) from src/
[PASS] using_dispatchers::call_and_invoke
Tests: 1 passed, 0 failed, 0 skipped
```
Now you have successfully created and tested your starknet contract using `snforge`.
## snforge Commands
- Running `snforge` in the Current Directory
To run the snforge command in the current directory, simply execute the following command:
### Test Filter Options
- `-e, --exact`: Use the `-e` or `--exact` option to run a test with a name that exactly matches the provided test filter. The test filter should be a fully qualified test name, including the package name. For example, instead of specifying just `my_test`, use `package_name::my_test` as the test filter.
- `--init` <NAME>: The `--init` <NAME> option allows you to create a new directory and forge project with the specified name <NAME>.
- `-x`, `--exit-first`: By using the` -x` or `--exit-first` option, you can stop the execution of tests after the first test failure is encountered.
### Package Selection
- `-p`, `--package`: The `-p` or `--package` option is used to specify the packages on which to run the `snforge` command. You can either provide a concrete package name (e.g., foobar) or use a prefix glob (e.g., foo\*) to match multiple packages.
- `-w`, `--workspace`: Use the `-w` or `--workspace` option to run tests for all packages in the workspace.
### Fuzzer Configuration
- `-r`, `--fuzzer-runs` <FUZZER_RUNS>: Specify the number of fuzzer runs using the `-r` or `--fuzzer-runs` option, followed by the desired number of runs <FUZZER_RUNS>.
- `-s`, `--fuzzer-seed` <FUZZER_SEED>: Set the seed for the fuzzer by using the `-s` or `--fuzzer-seed` option, followed by the desired seed value <FUZZER_SEED>.
### Cache Management
- `-c`, `--clean-cache`: To clean the `snforge` cache directory, simply use the `-c` or `--clean-cache` option.
### Help and Version Information
- `-h`,` --help`: Use the `-h` or `--help` option to print the help information, providing guidance on how to use `snforge`.
- `-V`, `--version`: To display the current version of `snforge`, use the `-V` or `--version` option.
Note: Replace <NAME>, <FUZZER_RUNS>, and <FUZZER_SEED> with your specific values when using the `snforge` command.
```

0 comments on commit 9f87efa

Please sign in to comment.