Merge pull request #514 from TypedDevs/feat/add-learn-mode-and-common-patterns

Add learn mode and common patterns

Author: Chemaclass

.github/workflows/static_analysis.yml

@@ -24,5 +24,5 @@ jobs:
       - name: Run ShellCheck
         uses: ludeeus/action-shellcheck@master
         env:
-          SHELLCHECK_OPTS: -e SC1091 -e SC2155
+          SHELLCHECK_OPTS: -e SC1091 -e SC2155 -e SC2016
 

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Added
+- Add `--learn` interactive tutorial with 10 progressive lessons for hands-on learning
+- Add comprehensive "Common Patterns" documentation with real-world testing examples
+
+### Fixed
 - Pass arguments to mocked functions
 - Fix lifecycle hooks not catching failing commands (exit code errors)
 

bashunit

@@ -56,6 +56,7 @@ source "$BASHUNIT_ROOT_DIR/src/reports.sh"
 source "$BASHUNIT_ROOT_DIR/src/runner.sh"
 source "$BASHUNIT_ROOT_DIR/src/bashunit.sh"
 source "$BASHUNIT_ROOT_DIR/src/init.sh"
+source "$BASHUNIT_ROOT_DIR/src/learn.sh"
 source "$BASHUNIT_ROOT_DIR/src/main.sh"
 
 _ASSERT_FN=""
@@ -141,6 +142,10 @@ while [[ $# -gt 0 ]]; do
       fi
       trap '' EXIT && exit 0
       ;;
+    --learn)
+      learn::start
+      trap '' EXIT && exit 0
+      ;;
     -h|--help)
       console_header::print_help
       trap '' EXIT && exit 0

build.sh

@@ -104,6 +104,7 @@ function build::dependencies() {
     "src/reports.sh"
     "src/runner.sh"
     "src/init.sh"
+    "src/learn.sh"
     "src/bashunit.sh"
     "src/main.sh"
   )

docs/.vitepress/config.ts

@@ -87,6 +87,9 @@ export default defineConfig({
       }, {
         text: 'Custom asserts',
         link: '/custom-asserts'
+      }, {
+        text: 'Common patterns',
+        link: '/common-patterns',
       }, {
         text: 'Examples',
         link: '/examples'

docs/command-line.md

@@ -399,6 +399,58 @@ When a custom directory is used, bashunit writes `BASHUNIT_BOOTSTRAP=<dir>/boots
 ```
 :::
 
+## Learn
+
+> `bashunit --learn`
+
+Starts an interactive learning tutorial that teaches you how to use bashunit step by step through hands-on exercises.
+
+The tutorial covers:
+- Writing your first test
+- Using different assertions
+- Setup and teardown functions
+- Testing functions and scripts
+- Mocking external dependencies
+- Using spies to verify calls
+- Parameterized testing with data providers
+- Testing exit codes
+- A complete real-world challenge
+
+Your progress is saved automatically, and you can resume at any time.
+
+::: code-group
+```bash [Example]
+./bashunit --learn
+```
+```[Output]
+bashunit - Interactive Learning
+
+Choose a lesson:
+
+  1. Basics - Your First Test
+  2. Assertions - Testing Different Conditions
+  3. Setup & Teardown - Managing Test Lifecycle
+  4. Testing Functions - Unit Testing Patterns
+  5. Testing Scripts - Integration Testing
+  6. Mocking - Test Doubles and Mocks
+  7. Spies - Verifying Function Calls
+  8. Data Providers - Parameterized Tests
+  9. Exit Codes - Testing Success and Failure
+  10. Complete Challenge - Real World Scenario
+
+  p. Show Progress
+  r. Reset Progress
+  q. Quit
+
+Enter your choice:
+```
+:::
+
+::: tip
+The learn mode is perfect for new users getting started with bashunit.
+It provides practical, hands-on experience with immediate feedback.
+:::
+
 ## Help
 
 > `bashunit --help`