From bab99daa823026828c5c8e9ea2df28aa5c6580bf Mon Sep 17 00:00:00 2001
From: Cheng Liu <chengcyber@users.noreply.github.com>
Date: Thu, 7 Mar 2024 11:27:54 -0800
Subject: [PATCH] :memo:

---
 build-tests/sparo-real-repo-test/README.md |  6 +--
 build-tests/test-utilities/README.md       | 48 +++++++++++++++++++---
 2 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/build-tests/sparo-real-repo-test/README.md b/build-tests/sparo-real-repo-test/README.md
index e33eac7..012cea8 100644
--- a/build-tests/sparo-real-repo-test/README.md
+++ b/build-tests/sparo-real-repo-test/README.md
@@ -1,6 +1,6 @@
-# sparo-output-test
+# sparo-real-repo-test
 
-Building this project tests sparo command outputs
+Building this project tests sparo command outputs with a real GitHub repo
 
 # Details
 
@@ -8,4 +8,4 @@ Building this project tests sparo command outputs
 
 # How to fix the build errors
 
-Run `rush build -t sparo-output-test` to regenerate files under `etc` folder and commit them into Git.
\ No newline at end of file
+Run `rush build -t sparo-real-repo-test` to regenerate files under `etc` folder and commit them into Git.
\ No newline at end of file
diff --git a/build-tests/test-utilities/README.md b/build-tests/test-utilities/README.md
index e33eac7..7cc768b 100644
--- a/build-tests/test-utilities/README.md
+++ b/build-tests/test-utilities/README.md
@@ -1,11 +1,47 @@
-# sparo-output-test
+# build-test-utilities
 
-Building this project tests sparo command outputs
+The project contains several utility function for build tests.
 
-# Details
+# Test sparo output with Heft run-script plugin
 
-`lib/start-test.js` is run after building the project. This scripts generate the output text files under `temp/etc`. In local builds, those files are copied to `etc` folder. During a CI build, the files under these two folders are compared and the CI build fails if they are different. This ensures that files under `etc` folder must be up to date in the PR, and people who review the PR must approve any changes.
+```ts
+import {
+  ICommandDefinition,
+  executeCommandsAndCollectOutputs,
+  updateOrCompareOutputs
+} from 'build-test-utilities';
+import type { IRunScriptOptions } from '@rushstack/heft';
 
-# How to fix the build errors
+export async function runAsync(runScriptOptions: IRunScriptOptions): Promise<void> {
+  const {
+    heftTaskSession: {
+      logger,
+      parameters: { production }
+    },
+    heftConfiguration: { buildFolderPath }
+  } = runScriptOptions;
 
-Run `rush build -t sparo-output-test` to regenerate files under `etc` folder and commit them into Git.
\ No newline at end of file
+  const commandDefinitions: ICommandDefinition[] = [
+    {
+      kind: 'sparo-command',
+      name: 'clone-help',
+      args: ['clone', '--help']
+    }
+  ];
+
+  await executeCommandsAndCollectOutputs({
+    commandDefinitions,
+    buildFolderPath,
+  })
+
+  await updateOrCompareOutput({
+    buildFolderPath,
+    logger,
+    production,
+  }) 
+}
+```
+
+`executeCommandsAndCollectOutputs` runs the list of specified command definitions, it collects sparo command outputs and save them to `<buildFolderPath>/temp/etc`.
+
+`updateOrCompareOutput` copies the output text files from `<buildFolderPath>/temp/etc` to `<buildFolderPath>/etc`, this ensures the output text files are always up to date, and it must get reviewed in the PR. In CI builds, this function will compares the content between these two folders, and throw a error for unmatched content.
\ No newline at end of file