From 4e166f7750c214e4cc636419f32c017dbe6e4ace Mon Sep 17 00:00:00 2001
From: Mahmoud Emad <mahmmoud.hassanein@gmail.com>
Date: Thu, 8 May 2025 15:05:55 +0300
Subject: [PATCH] docs: Add documentation for running Rhai tests

- Added a comprehensive guide on running Rhai tests within the
  SAL library.  This includes instructions for running all tests,
  tests for specific modules, and individual tests.
- Created a shell script (`run_rhai_tests.sh`) to simplify running
  all Rhai tests and provide a summary of results.  This improves
  the testing workflow and makes it easier to identify failures.
---
 docs/rhai/running_tests.md | 76 ++++++++++++++++++++++++++++++++++++++
 run_rhai_tests.sh          | 63 +++++++++++++++++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 docs/rhai/running_tests.md
 create mode 100755 run_rhai_tests.sh

diff --git a/docs/rhai/running_tests.md b/docs/rhai/running_tests.md
new file mode 100644
index 0000000..ae871f3
--- /dev/null
+++ b/docs/rhai/running_tests.md
@@ -0,0 +1,76 @@
+# Running Rhai Tests
+
+This document describes how to run the Rhai tests for the SAL library.
+
+## Test Structure
+
+The Rhai tests are organized by module in the `src/rhai_tests` directory:
+
+- `src/rhai_tests/os/`: Tests for the OS module
+- `src/rhai_tests/git/`: Tests for the Git module
+
+Each module directory contains:
+- Individual test scripts (e.g., `01_file_operations.rhai`)
+- A test runner script (`run_all_tests.rhai`) that runs all tests for that module
+
+## Running Tests
+
+### Running All Tests
+
+To run all Rhai tests across all modules, use the provided shell script:
+
+```bash
+./run_rhai_tests.sh
+```
+
+This script:
+1. Finds all test runner scripts in the `src/rhai_tests` directory
+2. Runs each test runner
+3. Reports the results for each module
+4. Provides a summary of all test results
+
+The script will exit with code 0 if all tests pass, or code 1 if any tests fail.
+
+### Running Tests for a Specific Module
+
+To run tests for a specific module, use the `herodo` command with the module's test runner:
+
+```bash
+herodo --path src/rhai_tests/os/run_all_tests.rhai
+```
+
+### Running Individual Tests
+
+To run a specific test, use the `herodo` command with the test script:
+
+```bash
+herodo --path src/rhai_tests/os/01_file_operations.rhai
+```
+
+## Test Output
+
+The test output includes:
+- Information about what's being tested
+- Success or failure messages for each test
+- A summary of test results
+
+Successful tests are indicated with a checkmark (✓), while failed tests show an error message.
+
+## Adding New Tests
+
+When adding new tests:
+
+1. Create a new test script in the appropriate module directory
+2. Update the module's test runner script to include the new test
+3. Update the module's documentation to describe the new test
+
+The `run_rhai_tests.sh` script will automatically find and run the new tests as long as they're included in a module's test runner script.
+
+## Troubleshooting
+
+If tests fail, check the following:
+
+1. Make sure the `herodo` binary is in your PATH
+2. Verify that the test scripts have the correct permissions
+3. Check for any dependencies required by the tests (e.g., `git` for Git module tests)
+4. Look for specific error messages in the test output
diff --git a/run_rhai_tests.sh b/run_rhai_tests.sh
new file mode 100755
index 0000000..58419d6
--- /dev/null
+++ b/run_rhai_tests.sh
@@ -0,0 +1,63 @@
+#!/bin/bash
+# run_rhai_tests.sh
+# Script to run all Rhai tests in the rhai_tests directory
+
+# Set colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Print header
+echo -e "${BLUE}=======================================${NC}"
+echo -e "${BLUE}      Running All Rhai Tests          ${NC}"
+echo -e "${BLUE}=======================================${NC}"
+
+# Find all test runner scripts
+RUNNERS=$(find src/rhai_tests -name "run_all_tests.rhai")
+
+# Initialize counters
+TOTAL_MODULES=0
+PASSED_MODULES=0
+FAILED_MODULES=0
+
+# Run each test runner
+for runner in $RUNNERS; do
+    # Extract module name from path
+    module=$(echo $runner | cut -d'/' -f3)
+    
+    echo -e "\n${YELLOW}Running tests for module: ${module}${NC}"
+    echo -e "${YELLOW}-------------------------------------${NC}"
+    
+    # Run the test runner
+    herodo --path $runner
+    
+    # Check if the test passed
+    if [ $? -eq 0 ]; then
+        echo -e "${GREEN}✓ Module ${module} tests passed${NC}"
+        PASSED_MODULES=$((PASSED_MODULES + 1))
+    else
+        echo -e "${RED}✗ Module ${module} tests failed${NC}"
+        FAILED_MODULES=$((FAILED_MODULES + 1))
+    fi
+    
+    TOTAL_MODULES=$((TOTAL_MODULES + 1))
+done
+
+# Print summary
+echo -e "\n${BLUE}=======================================${NC}"
+echo -e "${BLUE}            Test Summary              ${NC}"
+echo -e "${BLUE}=======================================${NC}"
+echo -e "Total modules tested: ${TOTAL_MODULES}"
+echo -e "Passed: ${GREEN}${PASSED_MODULES}${NC}"
+echo -e "Failed: ${RED}${FAILED_MODULES}${NC}"
+
+# Set exit code based on test results
+if [ $FAILED_MODULES -eq 0 ]; then
+    echo -e "\n${GREEN}All tests passed!${NC}"
+    exit 0
+else
+    echo -e "\n${RED}Some tests failed!${NC}"
+    exit 1
+fi