sanad-agent: Skill for Claude Code

Sanad Client Testing & Interactive Verification Protocol

This guide defines the unified interactive testing and verification protocol for client, designed to let AI agents verify interfaces, debug logic, and run integration tests inside isolated Git worktrees.

The CLI is platform-neutral, but it is not an accessibility crawler for arbitrary Flutter applications: the target Sanad Client must be launched through client/lib/driver_main.dart so the required Flutter Driver and Sanad service extensions are registered. sanad-dev ui owns desktop/worktree discovery. Mobile and web targets require a reachable explicit --vm-url (or VM_SERVICE_URL) and the same driver entry point.

1. Testing Methods & Priority Rules

Non-Negotiable Testing Rules

• Format & Analyze Single-Gate: Do not run tests before verifying that static analysis and formatting pass for the files/surface being changed.
• Scope-Based Automated Tests: Run the focused unit/widget tests that cover the changed behavior. Run the full fast suite only for broad/shared-surface changes.
• E2E By Scope Only: Run E2E or integration tests only when the change affects real socket behavior, local daemon connection states, app/bootstrap runtime integration, worktree port/runtime isolation, client/daemon contracts, or another system boundary that mocks cannot validate.
• Sequential Execution Only For Port-Binding Tests: Use --concurrency=1 only for E2E/integration tests that bind system ports or exclusive resources. Do not apply it to normal unit/widget/fast suites.
• Clean Isolation: Run Unit and Widget tests locally without launching external servers or the local daemon.
• Desktop Interactive Last: Launch the Interactive UI Testing Protocol only when static tests cannot validate the behavior or when visual/runtime verification is explicitly needed.

Testing Priority Flowchart

graph TD
    Start([Code Change Complete]) --> P1[1. Format & Analyze: fvm flutter analyze]
    P1 -->|Pass| P2[2. Targeted Unit/Widget Tests]
    P1 -->|Fail| Fix1[Fix Syntax & Lint Issues] --> P1
    P2 -->|Pass| P3{Broad/shared surface?}
    P2 -->|Fail| Fix2[Fix Logic & State Cubits] --> P2
    P3 -->|Yes| P4[3. Full Fast Suite: fvm flutter test]
    P3 -->|No| P5{Runtime/contract/port boundary?}
    P4 -->|Pass| P5
    P4 -->|Fail| Fix3[Fix Regressions] --> P4
    P5 -->|Yes| P6[4. E2E/Integration Tests]
    P5 -->|No| P7{Needs live UI verification?}
    P6 -->|Pass| P7
    P6 -->|Fail| Fix4[Fix E2E Integration Logic] --> P6
    P7 -->|Yes| P8[5. Interactive UI Tests]
    P7 -->|No| Success([Verify & Done])
    P8 -->|Pass| Success
    P8 -->|Fail| Fix5[Fix Interactive Flow / Hot Restart] --> P8