Pester Testing Suite

Pester Testing Suite

To maintain professional stability in an agentic system, Gemma CLI includes a comprehensive automated test suite powered by Pester, the ubiquitous testing framework for PowerShell.

---

🧪 Why We Test

Gemma CLI interacts with your file system, web APIs, and system configuration. Automated tests ensure that:

1. Tool Logic remains correct (e.g., move_file doesn't delete files by accident).
2. API Payloads are formatted correctly for Google's servers.
3. UI Components (like the menu) handle edge cases without crashing the loop.
4. Unicode Support is preserved across all modules.

---

🚀 How to Run Tests

Ensure you are in the project root directory, then run:

Invoke-Pester -Path .	ests

This will discover and execute all .Tests.ps1 files in the tests/ folder.

---

📂 Key Test Files

Test File	Focus Area
ToolLoader.Tests.ps1	Verifies that tools are correctly registered and the Tiered Guidance Engine picks the right prompt for the right model.
Parser.Tests.ps1	Ensures the regex-based XML/Markdown parser can handle different tool-calling styles from the model.
Splatting.Tests.ps1	Tests the conversion of JSON API responses into PowerShell hashtables for tool execution.
readfile.Tests.ps1	Verifies file access, encoding handling, and safety checks for the read tool.

---

🛠️ Writing Tests for New Tools

If you are following the Tool Development Guide, you should also add a test file.

Best Practice Template (tests/my_tool.Tests.ps1):

Describe "My New Tool" {
    BeforeAll {
        # Securely load the tool using UTF8 to avoid parse errors
        $toolPath = Join-Path $PSScriptRoot "../tools/my_tool.ps1"
        $content = Get-Content -Path $toolPath -Raw -Encoding UTF8
        Invoke-Expression $content
    }

    It "should return the expected output for valid input" {
        $result = Invoke-MyNewTool -param1 "test"
        $result | Should Match "Expected Result"
    }

    It "should handle errors gracefully" {
        $result = Invoke-MyNewTool -param1 $null
        $result | Should Match "ERROR"
    }
}

---

⚠️ Important: Encoding & Emojis

Because Gemma CLI tools often use emojis in their FormatLabel field, the test runner must be careful with file encoding.

• Always use Get-Content -Raw -Encoding UTF8 when loading code in a BeforeAll block.
• The project includes a fix across all core tests to prevent "Unexpected token" errors caused by legacy PowerShell encoding.

---

🛠️ Supplemental Tools:

• Validate-JSON - Since Gemma CLI uses JSON for its "intelligence" and configuration, we recommend this Python-based utility to recursively validate all JSON files in the project in seconds. This script checks for syntax errors and encoding issues (e.g., ensuring files are UTF-8). Highly recommended after editing intelligence.json or settings.json

---

Next Steps: See the System Architecture to understand the core logic being tested here.