Split contract.md into multiple sections, add part on external contracts #3386

cptartur · 2025-05-21T12:53:02Z

Closes #

Introduced changes

Split contents of contract.md into multiple sections
Added a section on using external contracts. Until now it was buried in the docs on tests collection (left a mention of it there as well).

Checklist

kkawula · 2025-05-21T14:12:04Z

docs/src/SUMMARY.md

 # `snforge` Overview

 * [Running Tests](testing/running-tests.md)
 * [Writing Tests](testing/testing.md)


It is called the same as sub section

kkawula · 2025-05-21T14:14:01Z

docs/src/testing/contracts.md

[dev-dependencies] snforge_std = "0.44.0"

Changed here and in other place as well

kkawula · 2025-05-21T14:21:16Z

docs/src/testing/contracts.md

-Sometimes the test code failing can be a desired behavior.
-Instead of manually handling it, you can simply mark your test as `#[should_panic(...)]`.
-[See here](./testing.md#expected-failures) for more details.
+This chapter shows how to test smart contracts using Starknet Foundry.


Can we shorten this entire paragraph? It sounds a little clunky

I've shortened it

docs/src/testing/contracts/external-contracts.md

kkawula · 2025-05-21T14:38:44Z

docs/src/testing/contracts/writing_tests.md

+
+Note that the name after `mod` will be used as the contract name for testing purposes.
+
+## Writing Tests


This heading is duplicated and doesn't look good for me

Renamed the top level heading, I think it makes a bit more sense now

Co-authored-by: kkawula <[email protected]>

…ting-contracts-docs

franciszekjob · 2025-05-27T09:05:08Z

docs/src/testing/contracts/handling-errors.md

+Sometimes we want to test contracts functions that can panic, like testing that function that verifies caller address
+panics on invalid address. For that purpose Starknet also provides a `SafeDispatcher`, that returns a `Result` instead of
+panicking.


Suggested change

Sometimes we want to test contracts functions that can panic, like testing that function that verifies caller address

panics on invalid address. For that purpose Starknet also provides a `SafeDispatcher`, that returns a `Result` instead of

panicking.

Sometimes we want to test contract functions that may panic. For instance, an example of this would be a function which verifies caller address and panics when it encounters an invalid one. For that purpose Starknet provides `SafeDispatcher` that returns a `Result` instead of

panicking.

franciszekjob · 2025-05-27T09:08:38Z

docs/src/testing/contracts/handling-errors.md

+
+## `SafeDispatcher`
+
+Using `SafeDispatcher` we can test that the function in fact panics with an expected message.


Suggested change

Using `SafeDispatcher` we can test that the function in fact panics with an expected message.

By using `SafeDispatcher`, we can test that the function in fact panics with an expected message.

franciszekjob · 2025-05-27T09:09:46Z

docs/src/testing/contracts/handling-errors.md

+
+Sometimes the test code failing can be a desired behavior.
+Instead of manually handling it, you can simply mark your test as `#[should_panic(...)]`.
+[See here](../contracts/handling-errors.md#expecting-test-failure) for more details.


Suggested change

[See here](../contracts/handling-errors.md#expecting-test-failure) for more details.

See [here](../contracts/handling-errors.md#expecting-test-failure) for more details.

franciszekjob · 2025-05-27T09:12:57Z

docs/src/testing/contracts/external-contracts.md

+
+## Add a Dependency
+
+First, add a dependency on the contract package, either in `Scarb.toml` directly or by using `scarb add packageName`.


nit: Cairo packages are named with snake_case 😅 :

Suggested change

First, add a dependency on the contract package, either in `Scarb.toml` directly or by using `scarb add packageName`.

First, add a dependency on the contract package, either in `Scarb.toml` directly or by using `scarb add package_name`.

franciszekjob · 2025-05-27T09:14:12Z

docs/src/testing/contracts/external-contracts.md

+
+```toml
+[[target.starknet-contract]]
+build-external-contracts = ["externalPackage1::Contract1", "otherExternalPackage::path::to::Contract2"]


Same as above:

Suggested change

build-external-contracts = ["externalPackage1::Contract1", "otherExternalPackage::path::to::Contract2"]

build-external-contracts = ["external_package::Contract1", "other_external_package::path::to::Contract2"]

ddoktorski · 2025-06-03T10:03:42Z

docs/src/SUMMARY.md

 * [Writing Tests](testing/testing.md)
 * [Test Attributes](testing/test-attributes.md)
 * [Testing Smart Contracts](testing/contracts.md)
+    * [Writing Contracts Tests](testing/contracts/writing_tests.md)


Suggested change

* [Writing Contracts Tests](testing/contracts/writing_tests.md)

* [Writing Contract Tests](testing/contracts/writing_tests.md)

ddoktorski · 2025-06-03T10:04:37Z

docs/src/testing/contracts/writing_tests.md

@@ -0,0 +1,50 @@
+# Writing Contracts Tests
+
+## The Test Contract


Suggested change

## The Test Contract

## Test Contract

ddoktorski · 2025-06-03T10:07:50Z

docs/src/testing/contracts/writing_tests.md

+Collected 2 test(s) from testing_smart_contracts_handling_errors package
+Running 2 test(s) from tests/
+[FAIL] testing_smart_contracts_handling_errors_integrationtest::panic::failing
+
+Failure data:
+    (0x50414e4943 ('PANIC'), 0x444159544148 ('DAYTAH'))
+
+[PASS] testing_smart_contracts_handling_errors_integrationtest::handle_panic::handling_string_errors (l1_gas: ~0, l1_data_gas: ~96, l2_gas: ~280000)
+Running 0 test(s) from src/
+Tests: 1 passed, 1 failed, 0 skipped, 0 ignored, 0 filtered out
+
+Failures:
+    testing_smart_contracts_handling_errors_integrationtest::panic::failing


This is incorrect output for the example above

ddoktorski · 2025-06-03T10:09:42Z

docs/src/testing/contracts/handling-errors.md

+Failure data:
+    (0x50414e4943 ('PANIC'), 0x444159544148 ('DAYTAH'))
+
+[PASS] testing_smart_contracts_handling_errors_integrationtest::handle_panic::handling_string_errors (l1_gas: ~0, l1_data_gas: ~96, l2_gas: ~280000)


We show in the code snippet only the failing function test, so ideally the output shouldn't contain other tests

ddoktorski · 2025-06-03T10:21:05Z

docs/src/testing/contracts/handling-errors.md

+```rust
+{{#include ../../../listings/testing_smart_contracts_handling_errors/tests/handle_panic.cairo}}
+```
+You also could skip the de-serialization of the `panic_data`, and not use `try_deserialize_bytearray_error`, but this way you can actually use assertions on the `ByteArray` that was used to panic.


Suggested change

You also could skip the de-serialization of the `panic_data`, and not use `try_deserialize_bytearray_error`, but this way you can actually use assertions on the `ByteArray` that was used to panic.

You could also skip deserializing the `panic_data` and avoid using `try_deserialize_bytearray_error`, but in that case `panic_data` remains in its raw format as an array of felts.

github-actions · 2025-07-04T07:06:53Z

Hi! This pull request hasn't had any activity for a while, so I am
marking it as stale. It will close in 14
days if it is not updated. Thanks for contributing!

github-actions · 2025-07-18T07:08:53Z

This pull request has been automatically closed due to inactivity.
Feel free to reopen it or create a new one if needed.
Thanks for contributing!

Split contract.md into multiple sections, add part on external contracts

46dc2db

cptartur requested a review from a team as a code owner May 21, 2025 12:53

cptartur requested review from ddoktorski and kkawula May 21, 2025 12:53

kkawula reviewed May 21, 2025

View reviewed changes

docs/src/testing/contracts/external-contracts.md Outdated Show resolved Hide resolved

kkawula reviewed May 21, 2025

View reviewed changes

cptartur and others added 6 commits May 26, 2025 15:09

Rename duplicated header

5f5dc1c

Change heading levels

d63f17c

Bump snforge_std in docs

5f2fffa

Simplify paragraph

f08e16f

Update docs/src/testing/contracts/external-contracts.md

b0c8e66

Co-authored-by: kkawula <[email protected]>

Merge remote-tracking branch 'origin/testing-contracts-docs' into tes…

f84dd99

…ting-contracts-docs

cptartur requested a review from kkawula May 26, 2025 13:23

Merge branch 'master' into testing-contracts-docs

f0d0c65

franciszekjob reviewed May 27, 2025

View reviewed changes

ddoktorski reviewed Jun 3, 2025

View reviewed changes

github-actions bot added the stale Stale Bot label Jul 4, 2025

github-actions bot closed this Jul 18, 2025


		Note that the name after `mod` will be used as the contract name for testing purposes.

		## Writing Tests


		## `SafeDispatcher`

		Using `SafeDispatcher` we can test that the function in fact panics with an expected message.

	Using `SafeDispatcher` we can test that the function in fact panics with an expected message.
	By using `SafeDispatcher`, we can test that the function in fact panics with an expected message.

	[See here](../contracts/handling-errors.md#expecting-test-failure) for more details.
	See [here](../contracts/handling-errors.md#expecting-test-failure) for more details.


		## Add a Dependency

		First, add a dependency on the contract package, either in `Scarb.toml` directly or by using `scarb add packageName`.

	build-external-contracts = ["externalPackage1::Contract1", "otherExternalPackage::path::to::Contract2"]
	build-external-contracts = ["external_package::Contract1", "other_external_package::path::to::Contract2"]

	* [Writing Contracts Tests](testing/contracts/writing_tests.md)
	* [Writing Contract Tests](testing/contracts/writing_tests.md)

		@@ -0,0 +1,50 @@
		# Writing Contracts Tests

		## The Test Contract

	You also could skip the de-serialization of the `panic_data`, and not use `try_deserialize_bytearray_error`, but this way you can actually use assertions on the `ByteArray` that was used to panic.
	You could also skip deserializing the `panic_data` and avoid using `try_deserialize_bytearray_error`, but in that case `panic_data` remains in its raw format as an array of felts.

Split contract.md into multiple sections, add part on external contracts #3386

Split contract.md into multiple sections, add part on external contracts #3386

Uh oh!

Conversation

cptartur commented May 21, 2025

Introduced changes

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jul 4, 2025

Uh oh!

github-actions bot commented Jul 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants