From ab17deda0b9b2f59cf3c455af18825a80fa9db8f Mon Sep 17 00:00:00 2001
From: Kieron Wilkinson <kieron.wilkinson@gmail.com>
Date: Mon, 28 Oct 2024 20:46:18 +0000
Subject: [PATCH] Example showing discovery and running of test commands
 (#1594)

* Example showing discovery and running of test commands

* Updated to conform better with style guide, nupm testing, as well as suggestions from @fdncred
---
 book/testing.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/book/testing.md b/book/testing.md
index f1c5c9c072..819c479524 100644
--- a/book/testing.md
+++ b/book/testing.md
@@ -165,4 +165,57 @@ for t in [
 ```
 and be invoked as `nu tests.nu`
 
+### Basic Test Framework
+
+It is also possible to define tests in Nushell as functions with descriptive names and discover
+them dynamically without requiring a [Nupm] package. The following uses `scope commands` and a
+second instance of Nushell to run the generated list of tests.
+
+```nushell
+use std assert
+
+source fib.nu
+
+def main [] {
+    print "Running tests..."
+
+    let test_commands = (
+        scope commands
+            | where ($it.type == "custom")
+                and ($it.name | str starts-with "test ")
+                and not ($it.description | str starts-with "ignore")
+            | get name
+            | each { |test| [$"print 'Running test: ($test)'", $test] } | flatten
+            | str join "; "
+    )
+
+    nu --commands $"source ($env.CURRENT_FILE); ($test_commands)"
+    print "Tests completed successfully"
+}
+
+def "test fib" [] {
+    for t in [
+        [input, expected];
+        [0, 0],
+        [1, 1],
+        [2, 1],
+        [3, 2],
+        [4, 3],
+        [5, 5],
+        [6, 8],
+        [7, 13]
+    ] {
+        assert equal (fib $t.input) $t.expected
+    }
+}
+
+# ignore
+def "test show-ignored-test" [] {
+    print "This test will not be executed"
+}
+```
+
+This is a simple example but could be extended to include many of the things you might expect from
+a testing framework, including setup and tear down functions and test discovery across files.
+
 [Nupm]: https://github.com/nushell/nupm