- Whole table match scenario.

- Nonempty table match scenario.
- Skip testing on files named `README.md`.

Author: general-kroll-4-life

docs/walkthroughs/README.md

@@ -0,0 +1,18 @@
+
+# `stackql` walkthroughs
+
+All markdown documents hereunder, execept those named `README.md`, 
+are **provably working** examples of `stackql` in action.
+These materials serve as useful examples and reference materials for
+using `stackql`.  If you have some use case that you would like to see added here; please let us know! 
+
+
+All walkthrough files are testable with CI, leveraging annotations (eg: code block info strings)
+in order to setup, run, verify and tear down testing scenarios.  The tests *can* be run:
+
+- Locally, on your own machine.  Thats the whole idea; please mix and match and let us know any ideas thast occur.
+- Directly from CI.  Reports are generated and archived.
+- From test harnesses, such as robot framework.  This has not yet been implemented.
+
+
+

docs/walkthroughs/get-google-accelerator-types.md

@@ -0,0 +1,70 @@
+
+## Setup
+
+First, create a google service account key using the GCP Console, per [the GCP documentation](https://cloud.google.com/iam/docs/keys-create-delete).  Grant the service account at least `Viewer` role equivalent privileges, per [the GCP dumentation](https://cloud.google.com/iam/docs/create-service-agents#grant-roles).
+
+Then, do this in bash:
+
+```bash setup stackql-shell credentials-path=cicd/keys/testing/google-ro-credentials.json app-root-path=./test/tmp/.get-google-accel.stackql
+
+export GOOGLE_CREDENTIALS="$(cat <credentials-path>)";
+
+stackql shell --approot=<app-root-path>
+```
+
+## Method
+
+Do this in the `stackql` shell, replacing `<project>` with your GCP project name:
+
+```sql stackql-shell input required project=ryuki-it-sandbox-01 region=australia-southeast1-a
+
+registry pull google;
+
+select 
+  name, 
+  kind 
+FROM google.compute.accelerator_types 
+WHERE 
+  project = '<project>' 
+  AND zone = '<region>'
+ORDER BY
+  name desc
+;
+
+```
+
+## Result
+
+
+You will see something very much like this included in the output, presuming you have one VM (if you have zero, only the headers should appper, more VMs means more rows):
+
+```sql expectation stdout-contains-all
+|---------------------|-------------------------|
+|        name         |          kind           |
+|---------------------|-------------------------|
+| nvidia-tesla-t4-vws | compute#acceleratorType |
+|---------------------|-------------------------|
+| nvidia-tesla-t4     | compute#acceleratorType |
+|---------------------|-------------------------|
+| nvidia-tesla-p4-vws | compute#acceleratorType |
+|---------------------|-------------------------|
+| nvidia-tesla-p4     | compute#acceleratorType |
+|---------------------|-------------------------|
+```
+
+<!---  EXPECTATION
+google\ provider,\ version\ 'v24.11.00274'\ successfully\ installed
+goodbye
+-->
+
+<x-expectation style="display: none;">
+<stdout-contains-nonempty-table></stdout-contains-nonempty-table>
+</x-expectation>
+
+## Cleanup
+
+```bash teardown best-effort app-root-path=./test/tmp/.get-google-accel.stackql
+
+rm -rf <app-root-path>
+
+```

test/python/markdown_testing/markdown_testing.py

@@ -15,6 +15,9 @@
   - Support sequential markdown code block execution, leveraging [info strings](https://spec.commonmark.org/0.30/#info-string).
 """
 
+def eprint(*args, **kwargs):
+    print(*args, file=sys.stderr, **kwargs)
+
 class ASTNode(object):
 
     _STACKQL_SHELL_INVOCATION: str = 'stackql-shell'
@@ -120,6 +123,7 @@ def parse_markdown_file(self, file_path: str, lang=None) -> MdAST:
 class Expectation(object):
 
     _STDOUT_TABLE_CONTAINS_DATA: str = 'stdout-table-contains-data'
+    _STDOUT_CONTAINS_ALL:        str = 'stdout-contains-all'
 
     def __init__(self, node: ASTNode):
         self._node: ASTNode = node
@@ -142,7 +146,11 @@ def _contains_nonempty_table(self, s: str) -> bool:
 
     def passes_stdout(self, actual_stdout: str) -> bool:
         if self._node.has_annotation(self._STDOUT_TABLE_CONTAINS_DATA):
+            eprint(f'running expectation check: {self._STDOUT_TABLE_CONTAINS_DATA}')
             return self._contains_nonempty_table(actual_stdout)
+        if self._node.has_annotation(self._STDOUT_CONTAINS_ALL):
+            eprint(f'running expectation check: {self._STDOUT_CONTAINS_ALL}')
+            return self._node.get_text() in actual_stdout
         return True
 
     def passes_stderr(self, actual_stderr: str) -> bool:
@@ -240,7 +248,6 @@ def orchestrate(self, file_path: str) -> WorkloadDTO:
 
 class WalkthroughResult:
 
-
   def __init__(self, stdout_str :str, stderr_str :str, rc :int) -> None:
     self.stdout :str = stdout_str
     self.stderr :str = stderr_str
@@ -251,7 +258,7 @@ class SimpleRunner(object):
     def __init__(self, workload: WorkloadDTO):
         self._workload = workload
 
-    def run(self) -> Tuple[bytes, bytes]:
+    def run(self) -> WalkthroughResult:
         bash_path = shutil.which('bash')
         pr: subprocess.Popen = subprocess.Popen(
             self._workload.get_setup(),
@@ -282,13 +289,16 @@ def __init__(self):
         md_parser = MdParser()
         self._orchestrator: MdOrchestrator = MdOrchestrator(md_parser)
 
-    def run_all(self, walkthrough_inodes: List[str], recursive=True) -> List[WalkthroughResult]:
+    def run_all(self, walkthrough_inodes: List[str], recursive=True, skip_readme=True) -> List[WalkthroughResult]:
         results: List[WalkthroughResult] = []
         for inode_path in walkthrough_inodes:
             is_dir = os.path.isdir(inode_path)
             if is_dir:
                 for root, dirs, files in os.walk(inode_path):
                     for file in files:
+                        if skip_readme and file == 'README.md':
+                            eprint(f'Skipping README.md')
+                            continue
                         file_path = os.path.join(root, file)
                         print(f'File path: {file_path}')
                         workload: WorkloadDTO = self._orchestrator.orchestrate(file_path)
@@ -302,6 +312,9 @@ def run_all(self, walkthrough_inodes: List[str], recursive=True) -> List[Walkthr
                 continue
             is_file = os.path.isfile(inode_path)
             if is_file:
+                if skip_readme and file == 'README.md':
+                    eprint(f'Skipping README.md')
+                    continue
                 file_path = inode_path
                 workload: WorkloadDTO = self._orchestrator.orchestrate(file_path)
                 e2e: SimpleRunner = SimpleRunner(workload)
@@ -311,7 +324,7 @@ def run_all(self, walkthrough_inodes: List[str], recursive=True) -> List[Walkthr
             raise FileNotFoundError(f'Path not tractable: {inode_path}')
         return results
 
-def  main():
+def main():
     runner: AllWalkthroughsRunner = AllWalkthroughsRunner()
     results: List[WalkthroughResult] = runner.run_all([os.path.join(_REPOSITORY_ROOT_PATH, 'docs', 'walkthroughs')])
     for result in results: