Automatically validate sncast docs snippets

crates/docs/Cargo.toml

@@ -11,6 +11,9 @@ shell-words = "1.1.0"
 walkdir.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+toml_edit.workspace = true
+camino.workspace = true
+tempfile.workspace = true
 
 [features]
 testing = []

crates/docs/src/snippet.rs

@@ -1,6 +1,16 @@
+use std::sync::LazyLock;
+
 use regex::Regex;
 use serde::{Deserialize, Serialize};
 
+static RE_SNCAST: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new( r"(?ms)^(?:<!--\s*(?P<config>\{.*?\})\s*-->\n)?```shell\n\$ (?P<command>sncast .+?)\n```(?:\s*<details>\n<summary>Output:<\/summary>\n\n```shell\n(?P<output>[\s\S]+?)\n```[\s]*<\/details>)?").expect("Failed to create regex for sncast snippet")
+});
+
+static RE_SNFORGE: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new( r"(?ms)^(?:<!--\s*(?P<config>\{.*?\})\s*-->\n)?```shell\n\$ (?P<command>snforge .+?)\n```(?:\s*<details>\n<summary>Output:<\/summary>\n\n```shell\n(?P<output>[\s\S]+?)\n```[\s]*<\/details>)?").expect("Failed to create regex for snforge snippet")
+});
+
 #[derive(Clone, Debug)]
 pub struct SnippetType(String);
 
@@ -21,9 +31,9 @@ impl SnippetType {
     }
 
     #[must_use]
-    pub fn get_re(&self) -> Regex {
+    pub fn get_re(&self) -> &'static Regex {
         // The regex pattern is used to match the snippet, its config and the output. Example:
-        // <!-- { "ignored": true, "package_name": "xyz" } -->
+        // <!-- { content of snippet config JSON } -->
         // ```shell
         // $ snforge or sncast command with args...
         // ```
@@ -34,19 +44,20 @@ impl SnippetType {
         // ```
         // </details>
 
-        let escaped_command = regex::escape(self.as_str());
-        let pattern = format!(
-            r"(?ms)^(?:<!--\s*(?P<config>.*?)\s*-->\n)?```shell\n\$ (?P<command>{escaped_command} .+?)\n```(?:\s*<details>\n<summary>Output:<\/summary>\n\n```shell\n(?P<output>[\s\S]+?)\n```[\s]*<\/details>)?"
-        );
-
-        Regex::new(&pattern).unwrap()
+        match self.as_str() {
+            "snforge" => &RE_SNFORGE,
+            "sncast" => &RE_SNCAST,
+            _ => panic!("Regex for {} not found", self.as_str()),
+        }
     }
 }
 
 #[derive(Debug, Deserialize, Serialize, Default)]
 pub struct SnippetConfig {
     pub ignored: Option<bool>,
     pub package_name: Option<String>,
+    pub contract_name: Option<String>,
+    pub ignored_output: Option<bool>,
 }
 
 #[derive(Debug)]

crates/docs/src/utils.rs

@@ -1,6 +1,8 @@
-use std::{env, path::PathBuf};
-
 use crate::snippet::Snippet;
+use camino::Utf8PathBuf;
+use std::{env, fs, path::PathBuf, str::FromStr};
+use tempfile::TempDir;
+use toml_edit::{value, DocumentMut};
 
 #[must_use]
 pub fn get_nth_ancestor(levels_up: usize) -> PathBuf {
@@ -27,15 +29,46 @@ pub fn assert_valid_snippet(condition: bool, snippet: &Snippet, err_message: &st
     );
 }
 
-pub fn print_success_message(snippets_len: usize, tool_name: &str) {
-    println!("Successfully validated {snippets_len} {tool_name} docs snippets");
+pub fn print_snippets_validation_summary(snippets: &[Snippet], tool_name: &str) {
+    let validated_snippets_count = snippets
+        .iter()
+        .filter(|snippet| !snippet.config.ignored.unwrap_or(false))
+        .count();
+    let ignored_snippets_count = snippets.len() - validated_snippets_count;
+
+    println!("Finished validation of {tool_name} docs snippets\nValidated: {validated_snippets_count}, Ignored: {ignored_snippets_count}");
 }
 
-pub fn print_skipped_snippet_message(snippet: &Snippet) {
+pub fn print_ignored_snippet_message(snippet: &Snippet) {
     println!(
-        "Skipped validation of {} snippet in the docs in file: {} at line {}",
+        "Ignoring {} docs snippet, file: {}:{}:1",
         snippet.snippet_type.as_str(),
         snippet.file_path,
         snippet.line_start,
     );
 }
+
+fn get_canonical_path(relative_path: &str) -> Result<String, Box<dyn std::error::Error>> {
+    Ok(Utf8PathBuf::from_str(relative_path)?
+        .canonicalize_utf8()?
+        .to_string()
+        .replace('\\', "/"))
+}
+
+pub fn update_scarb_toml_dependencies(temp: &TempDir) -> Result<(), Box<dyn std::error::Error>> {
+    let snforge_std_path = get_canonical_path("../../snforge_std")?;
+    let sncast_std_path = get_canonical_path("../../sncast_std")?;
+    let scarb_toml_path = temp.path().join("Scarb.toml");
+
+    let mut scarb_toml = fs::read_to_string(&scarb_toml_path)
+        .unwrap()
+        .parse::<DocumentMut>()
+        .unwrap();
+
+    scarb_toml["dependencies"]["sncast_std"]["path"] = value(&sncast_std_path);
+    scarb_toml["dev-dependencies"]["snforge_std"]["path"] = value(&snforge_std_path);
+
+    fs::write(&scarb_toml_path, scarb_toml.to_string())?;
+
+    Ok(())
+}

crates/forge/tests/e2e/docs_snippets_validation.rs

@@ -1,7 +1,8 @@
 use clap::Parser;
 use docs::snippet::SnippetType;
 use docs::utils::{
-    assert_valid_snippet, get_nth_ancestor, print_skipped_snippet_message, print_success_message,
+    assert_valid_snippet, get_nth_ancestor, print_ignored_snippet_message,
+    print_snippets_validation_summary,
 };
 use docs::validation::extract_snippets_from_directory;
 use forge::Cli;
@@ -20,14 +21,14 @@ fn test_docs_snippets() {
         .expect("Failed to extract command snippets");
 
     for snippet in &snippets {
-        let args = snippet.to_command_args();
-        let mut args: Vec<&str> = args.iter().map(String::as_str).collect();
-
         if snippet.config.ignored.unwrap_or(false) {
-            print_skipped_snippet_message(snippet);
+            print_ignored_snippet_message(snippet);
             continue;
         }
 
+        let args = snippet.to_command_args();
+        let mut args: Vec<&str> = args.iter().map(String::as_str).collect();
+
         let parse_result = Cli::try_parse_from(args.clone());
         let err_message = if let Err(err) = &parse_result {
             err.to_string()
@@ -55,5 +56,5 @@ fn test_docs_snippets() {
         }
     }
 
-    print_success_message(snippets.len(), snippet_type.as_str());
+    print_snippets_validation_summary(&snippets, snippet_type.as_str());
 }

crates/sncast/README.md

@@ -31,156 +31,186 @@ All subcommand usages are shown for two scenarios - when all necessary arguments
 
 ### Declare a contract
 
+<!-- TODO(#2736) -->
+<!-- { "ignored": true } -->
 ```shell
-$ sncast --account myuser \
+$ sncast --account user0 \
     declare \
-    --contract-name SimpleBalance
+    --contract-name HelloSncast \
+    --fee-token strk
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
 command: Declare
-class_hash: 0x8448a68b5ea1affc45e3fd4b8b480ea36a51dc34e337a16d2567d32d0c6f8a
-transaction_hash: 0x7ad0d6e449e33b6581a4bb8df866c0fce3919a5ee05a30840ba521dafee217f
+class_hash: [..]
+transaction_hash: [..]
 ```
 </details>
 <br>
 
 With arguments taken from `snfoundry.toml` file (default profile name):
 
+<!-- TODO(#2736) -->
+<!-- { "ignored": true } -->
 ```shell
 $ sncast declare \
-    --contract-name SimpleBalance
+    --contract-name HelloSncast \
+    --fee-token strk
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
 command: Declare
-class_hash: 0x8448a68b5ea1affc45e3fd4b8b480ea36a51dc34e337a16d2567d32d0c6f8a
-transaction_hash: 0x7ad0d6e449e33b6581a4bb8df866c0fce3919a5ee05a30840ba521dafee217f
+class_hash: [..]
+transaction_hash: [..]
 ```
 </details>
 <br>
 
 
 ### Deploy a contract
 
+<!-- TODO(#2736) -->
+<!-- { "contract_name": "HelloSncast", "ignored": true } -->
 ```shell
-$ sncast --account myuser \
-    deploy --class-hash 0x8448a68b5ea1affc45e3fd4b8b480ea36a51dc34e337a16d2567d32d0c6f8a \
-    --url http://127.0.0.1:5050/rpc \
+$ sncast --account user0 \
+    deploy --class-hash 0x0555d84fd95ab9fa84a826382ca91127336d4b3c640d8571c32c4e7717e38799 \
+    --url http://127.0.0.1:5055 \
+    --fee-token strk
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
 command: Deploy
-contract_address: 0x301316d47a81b39c5e27cca4a7b8ca4773edbf1103218588d6da4d3ed53035a
-transaction_hash: 0x64a62a000240e034d1862c2bbfa154aac6a8195b4b2e570f38bf4fd47a5ab1e
+contract_address: [..]
+transaction_hash: [..]
 ```
 </details>
 <br>
 
 With arguments taken from `snfoundry.toml` file (default profile name):
 
+<!-- TODO(#2736) -->
+<!-- { "contract_name": "HelloSncast", "ignored": true } -->
 ```shell
-$ sncast deploy --class-hash 0x8448a68b5ea1affc45e3fd4b8b480ea36a51dc34e337a16d2567d32d0c6f8a
+$ sncast deploy \
+--class-hash 0x0555d84fd95ab9fa84a826382ca91127336d4b3c640d8571c32c4e7717e38799 \
+--fee-token strk
+
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
 command: Deploy
-contract_address: 0x301316d47a81b39c5e27cca4a7b8ca4773edbf1103218588d6da4d3ed53035a
-transaction_hash: 0x64a62a000240e034d1862c2bbfa154aac6a8195b4b2e570f38bf4fd47a5ab1e
+contract_address: [..]
+transaction_hash: [..]
 ```
 </details>
 <br>
 
 
 ### Invoke a contract
 
+<!-- { "contract_name": "HelloSncast" } -->
 ```shell
 $ sncast \
-    --account example_user \
+    --account user0 \
     invoke \
-    --contract-address 0x4a739ab73aa3cac01f9da5d55f49fb67baee4919224454a2e3f85b16462a911 \
-    --function "some_function" \
-    --arguments '1, 2, 3'
+    --contract-address 0x0555d84fd95ab9fa84a826382ca91127336d4b3c640d8571c32c4e7717e38799 \
+    --function "sum_numbers" \
+    --arguments '1, 2, 3' \
+    --url http://127.0.0.1:5055/rpc \
+    --fee-token strk
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
-command: Invoke
-transaction_hash: 0x7ad0d6e449e33b6581a4bb8df866c0fce3919a5ee05a30840ba521dafee217f
+command: invoke
+transaction_hash: [..]
+
+To see invocation details, visit:
+transaction: https://sepolia.starkscan.co/tx/[..]
 ```
 </details>
 <br>
 
 
 With arguments taken from `snfoundry.toml` file (default profile name):
 
+<!-- { "contract_name": "HelloSncast" } -->
 ```shell
 $ sncast invoke \
-    --contract-address 0x4a739ab73aa3cac01f9da5d55f49fb67baee4919224454a2e3f85b16462a911 \
-    --function "some_function" \
-    --arguments '1, 2, 3'
+    --contract-address 0x0555d84fd95ab9fa84a826382ca91127336d4b3c640d8571c32c4e7717e38799 \
+    --function "sum_numbers" \
+    --arguments '1, 2, 3' \
+    --url http://127.0.0.1:5055/rpc \
+    --fee-token strk
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
-command: Invoke
-transaction_hash: 0x7ad0d6e449e33b6581a4bb8df866c0fce3919a5ee05a30840ba521dafee217f
+command: invoke
+transaction_hash: [..]
+
+To see invocation details, visit:
+transaction: https://sepolia.starkscan.co/tx/[..]
 ```
 </details>
 <br>
 
 ### Call a contract
 
+<!-- { "contract_name": "HelloSncast" } -->
 ```shell
 $ sncast \
     call \
-    --contract-address 0x4a739ab73aa3cac01f9da5d55f49fb67baee4919224454a2e3f85b16462a911 \
-    --function "some_function" \
-    --arguments '1, 2, 3'
+    --contract-address 0x0555d84fd95ab9fa84a826382ca91127336d4b3c640d8571c32c4e7717e38799 \
+    --function "sum_numbers" \
+    --arguments '1, 2, 3' \
+    --url http://127.0.0.1:5055/rpc
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
 command: call
-response: [0x0]
+response: [0x6]
 ```
 </details>
 <br>
 
 
 With arguments taken from `snfoundry.toml` file (default profile name):
 
+<!-- { "contract_name": "HelloSncast" } -->
 ```shell
 $ sncast call \
-    --contract-address 0x4a739ab73aa3cac01f9da5d55f49fb67baee4919224454a2e3f85b16462a911 \
-    --function "some_function" \
-    --arguments '1, 2, 3'
+    --contract-address 0x0555d84fd95ab9fa84a826382ca91127336d4b3c640d8571c32c4e7717e38799 \
+    --function "sum_numbers" \
+    --arguments '1, 2, 3' \
+    --url http://127.0.0.1:5055/rpc
 ```
 
 <details>
 <summary>Output:</summary>
 
 ```shell
 command: call
-response: [0x0]
+response: [0x6]
 ```
 </details>
 <br>