From 9d9f2abffca0ecd106aa8925765f47bfa39abe0f Mon Sep 17 00:00:00 2001
From: kkawula <57270771+kkawula@users.noreply.github.com>
Date: Tue, 1 Oct 2024 11:45:06 +0200
Subject: [PATCH] Explain `assert_macros` in the guide (#2531)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!-- Reference any GitHub issues resolved by this PR -->

Closes #2481

## Introduced changes

<!-- A brief description of the changes -->

- Added info about `assert_macros` in docs

## Checklist

<!-- Make sure all of these are complete -->

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [x] Added relevant tests
- [x] Performed self-review of the code
- [x] Added changes to `CHANGELOG.md`

---------

Co-authored-by: Artur Michałek <52135326+cptartur@users.noreply.github.com>
---
 docs/src/testing/testing.md          | 23 +++++++++++++++++++++++
 docs/src/testing/using-cheatcodes.md |  4 ++++
 2 files changed, 27 insertions(+)

diff --git a/docs/src/testing/testing.md b/docs/src/testing/testing.md
index ac6f58158..9d712e00f 100644
--- a/docs/src/testing/testing.md
+++ b/docs/src/testing/testing.md
@@ -105,3 +105,26 @@ Tests: 0 passed, 0 failed, 0 skipped, 1 ignored, 0 filtered out
 
 To run only tests marked with the  `#[ignore]` attribute use `snforge test --ignored`.
 To run all tests regardless of the `#[ignore]` attribute use `snforge test --include-ignored`.
+
+## Writing Assertions and `assert_macros` Package
+> ⚠️ **Recommended only for development** ️⚠️
+> 
+>***Assert macros package provides a set of macros that can be used to write assertions such as `assert_eq!`.
+In order to use it, your project must have the `assert_macros` dependency added to the `Scarb.toml` file.
+These macros are very expensive to run on Starknet, as they result a huge amount of steps and are not recommended for production use. 
+They are only meant to be used in tests.
+For snforge `v0.31.0` and later, this dependency is added automatically when creating a project using `snforge init`. But for earlier versions, you need to add it manually.***
+
+```toml
+[dev-dependencies]
+snforge_std = ...
+assert_macros = "<scarb-version>"
+```
+
+Available assert macros are 
+- `assert_eq!`
+- `assert_ne!`
+- `assert_lt!`
+- `assert_le!`
+- `assert_gt!`
+- `assert_ge!`
diff --git a/docs/src/testing/using-cheatcodes.md b/docs/src/testing/using-cheatcodes.md
index bb31b1e37..563a64656 100644
--- a/docs/src/testing/using-cheatcodes.md
+++ b/docs/src/testing/using-cheatcodes.md
@@ -14,6 +14,10 @@ When testing smart contracts, often there are parts of code that are dependent o
 Instead of trying to replicate these conditions in tests, you can emulate them
 using [cheatcodes](../appendix/cheatcodes.md).
 
+> ⚠️ **Warning**
+> 
+> These examples make use of `assert_macros`, so it's recommended to get familiar with them first. [Learn more about `assert_macros`](testing.md#writing-assertions-and-assert_macros-package)
+
 ## The Test Contract
 
 In this tutorial, we will be using the following Starknet contract: