From 19bc578e60d13a17f42e1ee7a960b1671985b9e4 Mon Sep 17 00:00:00 2001
From: Kazunobu Ndong <33208377+ndkazu@users.noreply.github.com>
Date: Tue, 10 Dec 2024 20:26:25 +0900
Subject: [PATCH] polkadot-sdk-docs: Use command_macro! (#6624)

# Description

**Understood assignment:**
Initial assignment description is in #6194.
In order to Simplify the display of commands and ensure they are tested
for chain spec builder's `polkadot-sdk` reference docs, find every
occurrence of `#[docify::export]` where `process:Command` is used, and
replace the use of `process:Command` by `run_cmd!` from the `cmd_lib
crate`.

---------

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
---
 Cargo.lock                                    |   2 +
 docs/sdk/Cargo.toml                           |   1 +
 docs/sdk/src/guides/your_first_node.rs        |  24 +-
 .../src/reference_docs/chain_spec_genesis.rs  |   8 +-
 .../chain_spec_runtime/Cargo.toml             |   1 +
 .../tests/chain_spec_builder_tests.rs         | 290 +++++++++---------
 prdoc/pr_6624.prdoc                           |  11 +
 7 files changed, 171 insertions(+), 166 deletions(-)
 create mode 100644 prdoc/pr_6624.prdoc

diff --git a/Cargo.lock b/Cargo.lock
index 8aa03954467d..989430fdfe29 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3171,6 +3171,7 @@ dependencies = [
 name = "chain-spec-guide-runtime"
 version = "0.0.0"
 dependencies = [
+ "cmd_lib",
  "docify",
  "frame-support 28.0.0",
  "pallet-balances 28.0.0",
@@ -19054,6 +19055,7 @@ version = "0.0.1"
 dependencies = [
  "assert_cmd",
  "chain-spec-guide-runtime",
+ "cmd_lib",
  "cumulus-client-service",
  "cumulus-pallet-aura-ext 0.7.0",
  "cumulus-pallet-parachain-system 0.7.0",
diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml
index 0c39367eeed3..0e4a5c001382 100644
--- a/docs/sdk/Cargo.toml
+++ b/docs/sdk/Cargo.toml
@@ -138,4 +138,5 @@ first-pallet = { workspace = true, default-features = true }
 
 [dev-dependencies]
 assert_cmd = "2.0.14"
+cmd_lib = { workspace = true }
 rand = "0.8"
diff --git a/docs/sdk/src/guides/your_first_node.rs b/docs/sdk/src/guides/your_first_node.rs
index da37c11c206f..3c782e4793ba 100644
--- a/docs/sdk/src/guides/your_first_node.rs
+++ b/docs/sdk/src/guides/your_first_node.rs
@@ -103,6 +103,7 @@
 #[cfg(test)]
 mod tests {
 	use assert_cmd::Command;
+	use cmd_lib::*;
 	use rand::Rng;
 	use sc_chain_spec::{DEV_RUNTIME_PRESET, LOCAL_TESTNET_RUNTIME_PRESET};
 	use sp_genesis_builder::PresetId;
@@ -173,13 +174,10 @@ mod tests {
 			println!("Building polkadot-sdk-docs-first-runtime...");
 			#[docify::export_content]
 			fn build_runtime() {
-				Command::new("cargo")
-					.arg("build")
-					.arg("--release")
-					.arg("-p")
-					.arg(FIRST_RUNTIME)
-					.assert()
-					.success();
+				run_cmd!(
+					cargo build --release -p $FIRST_RUNTIME
+				)
+				.expect("Failed to run command");
 			}
 			build_runtime()
 		}
@@ -274,14 +272,10 @@ mod tests {
 			let chain_spec_builder = find_release_binary(&CHAIN_SPEC_BUILDER).unwrap();
 			let runtime_path = find_wasm(PARA_RUNTIME).unwrap();
 			let output = "/tmp/demo-chain-spec.json";
-			Command::new(chain_spec_builder)
-				.args(["-c", output])
-				.arg("create")
-				.args(["--para-id", "1000", "--relay-chain", "dontcare"])
-				.args(["-r", runtime_path.to_str().unwrap()])
-				.args(["named-preset", "development"])
-				.assert()
-				.success();
+			let runtime_str = runtime_path.to_str().unwrap();
+			run_cmd!(
+				$chain_spec_builder -c $output create --para-id 1000 --relay-chain dontcare -r $runtime_str named-preset development
+			).expect("Failed to run command");
 			std::fs::remove_file(output).unwrap();
 		}
 		build_para_chain_spec_works();
diff --git a/docs/sdk/src/reference_docs/chain_spec_genesis.rs b/docs/sdk/src/reference_docs/chain_spec_genesis.rs
index b7a0a648d0cf..d5cc482711ad 100644
--- a/docs/sdk/src/reference_docs/chain_spec_genesis.rs
+++ b/docs/sdk/src/reference_docs/chain_spec_genesis.rs
@@ -174,13 +174,13 @@
 //! ```
 //! Here are some examples in the form of rust tests:
 //! ## Listing available preset names:
-#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", list_presets)]
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_list_presets)]
 //! ## Displaying preset with given name
-#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", get_preset)]
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_get_preset)]
 //! ## Building a solo chain-spec (the default) using given preset
-#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", generate_chain_spec)]
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_generate_chain_spec)]
 //! ## Building a parachain chain-spec using given preset
-#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", generate_para_chain_spec)]
+#![doc = docify::embed!("./src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs", cmd_generate_para_chain_spec)]
 //!
 //! [`RuntimeGenesisConfig`]:
 //!     chain_spec_guide_runtime::runtime::RuntimeGenesisConfig
diff --git a/docs/sdk/src/reference_docs/chain_spec_runtime/Cargo.toml b/docs/sdk/src/reference_docs/chain_spec_runtime/Cargo.toml
index 07c0342f5fbe..307e2daa38c6 100644
--- a/docs/sdk/src/reference_docs/chain_spec_runtime/Cargo.toml
+++ b/docs/sdk/src/reference_docs/chain_spec_runtime/Cargo.toml
@@ -42,6 +42,7 @@ substrate-wasm-builder = { optional = true, workspace = true, default-features =
 
 [dev-dependencies]
 chain-spec-builder = { workspace = true, default-features = true }
+cmd_lib = { workspace = true }
 sc-chain-spec = { workspace = true, default-features = true }
 
 [features]
diff --git a/docs/sdk/src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs b/docs/sdk/src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs
index df400b68f79d..b773af24de80 100644
--- a/docs/sdk/src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs
+++ b/docs/sdk/src/reference_docs/chain_spec_runtime/tests/chain_spec_builder_tests.rs
@@ -1,5 +1,6 @@
+use cmd_lib::*;
 use serde_json::{json, Value};
-use std::{process::Command, str};
+use std::str;
 
 fn wasm_file_path() -> &'static str {
 	chain_spec_guide_runtime::runtime::WASM_BINARY_PATH
@@ -8,189 +9,184 @@ fn wasm_file_path() -> &'static str {
 
 const CHAIN_SPEC_BUILDER_PATH: &str = "../../../../../target/release/chain-spec-builder";
 
+macro_rules! bash(
+	( chain-spec-builder $($a:tt)* ) => {{
+		let path = get_chain_spec_builder_path();
+		spawn_with_output!(
+			$path $($a)*
+		)
+		.expect("a process running. qed")
+		.wait_with_output()
+		.expect("to get output. qed.")
+
+	}}
+);
+
 fn get_chain_spec_builder_path() -> &'static str {
-	// dev-dependencies do not build binary. So let's do the naive work-around here:
-	let _ = std::process::Command::new("cargo")
-		.arg("build")
-		.arg("--release")
-		.arg("-p")
-		.arg("staging-chain-spec-builder")
-		.arg("--bin")
-		.arg("chain-spec-builder")
-		.status()
-		.expect("Failed to execute command");
+	run_cmd!(
+		cargo build --release -p staging-chain-spec-builder --bin chain-spec-builder
+	)
+	.expect("Failed to execute command");
 	CHAIN_SPEC_BUILDER_PATH
 }
 
+#[docify::export_content]
+fn cmd_list_presets(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder list-presets -r $runtime_path
+	)
+}
+
 #[test]
-#[docify::export]
 fn list_presets() {
-	let output = Command::new(get_chain_spec_builder_path())
-		.arg("list-presets")
-		.arg("-r")
-		.arg(wasm_file_path())
-		.output()
-		.expect("Failed to execute command");
-
-	let output: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+	let output: serde_json::Value =
+		serde_json::from_slice(cmd_list_presets(wasm_file_path()).as_bytes()).unwrap();
+	assert_eq!(
+		output,
+		json!({
+			"presets":[
+				"preset_1",
+				"preset_2",
+				"preset_3",
+				"preset_4",
+				"preset_invalid"
+			]
+		}),
+		"Output did not match expected"
+	);
+}
 
-	let expected_output = json!({
-		"presets":[
-			"preset_1",
-			"preset_2",
-			"preset_3",
-			"preset_4",
-			"preset_invalid"
-		]
-	});
-	assert_eq!(output, expected_output, "Output did not match expected");
+#[docify::export_content]
+fn cmd_get_preset(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder display-preset -r $runtime_path -p preset_2
+	)
 }
 
 #[test]
-#[docify::export]
 fn get_preset() {
-	let output = Command::new(get_chain_spec_builder_path())
-		.arg("display-preset")
-		.arg("-r")
-		.arg(wasm_file_path())
-		.arg("-p")
-		.arg("preset_2")
-		.output()
-		.expect("Failed to execute command");
-
-	let output: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
-
-	//note: copy of chain_spec_guide_runtime::preset_2
-	let expected_output = json!({
-		"bar": {
-			"initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
-		},
-		"foo": {
-			"someEnum": {
-				"Data2": {
-					"values": "0x0c10"
-				}
+	let output: serde_json::Value =
+		serde_json::from_slice(cmd_get_preset(wasm_file_path()).as_bytes()).unwrap();
+	assert_eq!(
+		output,
+		json!({
+			"bar": {
+				"initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
 			},
-			"someInteger": 200
-		},
-	});
-	assert_eq!(output, expected_output, "Output did not match expected");
+			"foo": {
+				"someEnum": {
+					"Data2": {
+						"values": "0x0c10"
+					}
+				},
+				"someInteger": 200
+			},
+		}),
+		"Output did not match expected"
+	);
+}
+
+#[docify::export_content]
+fn cmd_generate_chain_spec(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder -c /dev/stdout create -r $runtime_path named-preset preset_2
+	)
 }
 
 #[test]
-#[docify::export]
 fn generate_chain_spec() {
-	let output = Command::new(get_chain_spec_builder_path())
-		.arg("-c")
-		.arg("/dev/stdout")
-		.arg("create")
-		.arg("-r")
-		.arg(wasm_file_path())
-		.arg("named-preset")
-		.arg("preset_2")
-		.output()
-		.expect("Failed to execute command");
-
-	let mut output: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
-
-	//remove code field for better readability
+	let mut output: serde_json::Value =
+		serde_json::from_slice(cmd_generate_chain_spec(wasm_file_path()).as_bytes()).unwrap();
 	if let Some(code) = output["genesis"]["runtimeGenesis"].as_object_mut().unwrap().get_mut("code")
 	{
 		*code = Value::String("0x123".to_string());
 	}
-
-	let expected_output = json!({
-	  "name": "Custom",
-	  "id": "custom",
-	  "chainType": "Live",
-	  "bootNodes": [],
-	  "telemetryEndpoints": null,
-	  "protocolId": null,
-	  "properties": { "tokenDecimals": 12, "tokenSymbol": "UNIT" },
-	  "codeSubstitutes": {},
-	  "genesis": {
-		"runtimeGenesis": {
-		  "code": "0x123",
-		  "patch": {
-			"bar": {
-			  "initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL"
-			},
-			"foo": {
-			  "someEnum": {
-				"Data2": {
-				  "values": "0x0c10"
+	assert_eq!(
+		output,
+		json!({
+		  "name": "Custom",
+		  "id": "custom",
+		  "chainType": "Live",
+		  "bootNodes": [],
+		  "telemetryEndpoints": null,
+		  "protocolId": null,
+		  "properties": { "tokenDecimals": 12, "tokenSymbol": "UNIT" },
+		  "codeSubstitutes": {},
+		  "genesis": {
+			"runtimeGenesis": {
+			  "code": "0x123",
+			  "patch": {
+				"bar": {
+				  "initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL"
+				},
+				"foo": {
+				  "someEnum": {
+					"Data2": {
+					  "values": "0x0c10"
+					}
+				  },
+				  "someInteger": 200
 				}
-			  },
-			  "someInteger": 200
+			  }
 			}
 		  }
-		}
-	  }
-	});
-	assert_eq!(output, expected_output, "Output did not match expected");
+		}),
+		"Output did not match expected"
+	);
+}
+
+#[docify::export_content]
+fn cmd_generate_para_chain_spec(runtime_path: &str) -> String {
+	bash!(
+		chain-spec-builder -c /dev/stdout create -c polkadot -p 1000 -r $runtime_path named-preset preset_2
+	)
 }
 
 #[test]
-#[docify::export]
 fn generate_para_chain_spec() {
-	let output = Command::new(get_chain_spec_builder_path())
-		.arg("-c")
-		.arg("/dev/stdout")
-		.arg("create")
-		.arg("-c")
-		.arg("polkadot")
-		.arg("-p")
-		.arg("1000")
-		.arg("-r")
-		.arg(wasm_file_path())
-		.arg("named-preset")
-		.arg("preset_2")
-		.output()
-		.expect("Failed to execute command");
-
-	let mut output: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
-
-	//remove code field for better readability
+	let mut output: serde_json::Value =
+		serde_json::from_slice(cmd_generate_para_chain_spec(wasm_file_path()).as_bytes()).unwrap();
 	if let Some(code) = output["genesis"]["runtimeGenesis"].as_object_mut().unwrap().get_mut("code")
 	{
 		*code = Value::String("0x123".to_string());
 	}
-
-	let expected_output = json!({
-	  "name": "Custom",
-	  "id": "custom",
-	  "chainType": "Live",
-	  "bootNodes": [],
-	  "telemetryEndpoints": null,
-	  "protocolId": null,
-	  "relay_chain": "polkadot",
-	  "para_id": 1000,
-	  "properties": { "tokenDecimals": 12, "tokenSymbol": "UNIT" },
-	  "codeSubstitutes": {},
-	  "genesis": {
-		"runtimeGenesis": {
-		  "code": "0x123",
-		  "patch": {
-			"bar": {
-			  "initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL"
-			},
-			"foo": {
-			  "someEnum": {
-				"Data2": {
-				  "values": "0x0c10"
-				}
+	assert_eq!(
+		output,
+		json!({
+		"name": "Custom",
+		"id": "custom",
+		"chainType": "Live",
+		"bootNodes": [],
+		"telemetryEndpoints": null,
+		"protocolId": null,
+		"relay_chain": "polkadot",
+		"para_id": 1000,
+		"properties": { "tokenDecimals": 12, "tokenSymbol": "UNIT" },
+		"codeSubstitutes": {},
+		"genesis": {
+		  "runtimeGenesis": {
+			"code": "0x123",
+			"patch": {
+			  "bar": {
+				"initialAccount": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL"
 			  },
-			  "someInteger": 200
+			  "foo": {
+				"someEnum": {
+				  "Data2": {
+					"values": "0x0c10"
+				  }
+				},
+				"someInteger": 200
+			  }
 			}
 		  }
-		}
-	  }
-	});
-	assert_eq!(output, expected_output, "Output did not match expected");
+		}}),
+		"Output did not match expected"
+	);
 }
 
 #[test]
-#[docify::export]
+#[docify::export_content]
 fn preset_4_json() {
 	assert_eq!(
 		chain_spec_guide_runtime::presets::preset_4(),
diff --git a/prdoc/pr_6624.prdoc b/prdoc/pr_6624.prdoc
new file mode 100644
index 000000000000..4db55a46e8df
--- /dev/null
+++ b/prdoc/pr_6624.prdoc
@@ -0,0 +1,11 @@
+# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
+# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
+
+title: Use `cmd_lib` instead of `std::process::Command` when using `#[docify::export]`
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      Simplified the display of commands and ensured they are tested for chain spec builder's `polkadot-sdk` reference docs.
+
+crates: []
\ No newline at end of file