════════════════════════════════════════════════════════════════════════
  TEST STRATEGY
  Gnomad Desktop Assistant · docs/TEST_STRATEGY.md
════════════════════════════════════════════════════════════════════════

TEST STRATEGY — GNOMAD DESKTOP ASSISTANT
========================================

Status: Alpha — automated unit/integration tests + manual QA matrices  
Last updated: June 2026

────────────────────────────────────────

GOALS
-----

  1. Safety regressions never ship silently — HITL tokens, Path Gate, shell validation
  2. Cross-platform UI stays buildable — TypeScript + Vite on every push
  3. Release confidence — manual QA checklist per OS before tags

────────────────────────────────────────

TEST LAYERS
-----------

  Layer          |  Tooling                             |  Scope                                                               |  CI                 
  Rust unit      |  cargo test                          |  Tokens, privilege heuristics, parsers, env config, sandbox helpers  |  ✓ build.yml        
  Frontend unit  |  Vitest                              |  Error parsing, model normalization, mocked agent loop               |  ✓ build.yml        
  Build smoke    |  npm run build, cargo build          |  TS compile + Vite bundle                                            |  ✓                  
  Embedded LLM   |  cargo test --features embedded-llm  |  GGUF path (optional)                                                |  Manual / local only
  E2E GUI        |  Manual + QA_CHECKLIST.md            |  Tray, gates, updater, xterm                                         |  Pre-release        
  Security       |  Manual + external review (v1.0)     |  Pen test, token bypass attempts                                     |  v1.0               

────────────────────────────────────────

RUST TESTS (SRC-TAURI)
----------------------

Run: cd src-tauri && cargo test

  Module         |  What it guards                                        
  hitl_token     |  Issue/verify, replay rejection, boolean bypass blocked
  path_token     |  Same for filesystem scope                             
  privilege      |  Injection patterns, file-write detection              
  shell_session  |  Marker parsing, command validation                    
  shell_sandbox  |  Escape helpers, sandbox level constants               
  error          |  Stable JSON error codes                               
  env_config     |  Cloud base URL normalization                          

Optional feature:

  [bash]
    cargo test --features embedded-llm

────────────────────────────────────────

FRONTEND TESTS (SRC/)
---------------------

Run: npm run test

  File               |  What it guards                                     
  errors.test.ts     |  parseInvokeError, user-facing formatting           
  models.test.ts     |  Cloud model pickers, custom endpoint models        
  agentLoop.test.ts  |  Mock cloud turn → shell_run → completion; HITL deny

Gaps (future)

  • Component tests (React Testing Library) for gate modals
  • Playwright/Tauri WebDriver for one happy-path agent run
  • Updater E2E against a signed test release

────────────────────────────────────────

MANUAL QA (REQUIRED BEFORE RELEASE)
-----------------------------------

Use QA_CHECKLIST.md and CROSS_PLATFORM_CHECKLIST.md.

Minimum smoke:

  [code]
    npm run test && cd src-tauri && cargo test && npm run build
    npm run tauri dev   # interactive

Verify on each target OS you ship: macOS, Windows, Linux (X11 + Wayland if possible).

────────────────────────────────────────

CI MATRIX
---------

.github/workflows/build.yml:

  • macOS universal
  • Linux x86_64
  • Linux ARM64 (ubuntu-24.04-arm)
  • Windows

Release workflow adds signed updater JSON when keys are configured — see UPDATER.md.

────────────────────────────────────────

ADDING TESTS
------------

  1. Safety path changed? Add or extend Rust tests in the same module.
  2. Agent loop / IPC contract changed? Extend agentLoop.test.ts mocks.
  3. New user-facing error code? Add case to errors.test.ts.
  4. Doc-only change? npm run docs:export; no test required.

See CONTRIBUTING.md for PR checklist.

────────────────────────────────────────

RELATED
-------

  • TEST_NOTES.md — last local run log
  • QA_CHECKLIST.md — release sign-off
  • CODE_REVIEW.md — architecture for reviewers

────────────────────────────────────────

Built with ❤️ by Gnomad Studio 🦙

════════════════════════════════════════════════════════════════════════
Built with ❤️ by Gnomad Studio 🦙
https://gnomadstudio.org
════════════════════════════════════════════════════════════════════════