From d5485e616f864dc3a0d36f53d63cd98e4416b2ae Mon Sep 17 00:00:00 2001
From: Hikari <hikari@nhcarrigan.com>
Date: Sat, 7 Feb 2026 18:31:44 -0800
Subject: [PATCH] docs: add comprehensive testing guidelines to CLAUDE.md

Added detailed documentation covering:
- Coverage goal: maintain near-100% test coverage across codebase
- Console mocking strategies for preventing flaky tests
- E2E integration testing approach for cross-platform code
- Guidance for adding tests when developing new features

This documentation ensures future development maintains our excellent
test coverage and follows established testing patterns.
---
 CLAUDE.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 08d21e2..f4953d6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,6 +47,62 @@ All new features, fixes, and significant changes should include tests whenever p
 - Use descriptive test names that explain what behaviour is being tested
 - Include edge cases and error conditions in test coverage
 - Mock Tauri APIs using the patterns in `vitest.setup.ts`
+- **Coverage Goal**: Maintain as close to 100% test coverage as possible across the entire codebase
+
+### Mocking Strategies
+
+#### Console Mocking
+When testing code that intentionally logs errors (like error handling paths), mock console methods to prevent stderr output that makes tests appear flaky:
+
+```typescript
+it("handles errors gracefully", async () => {
+  const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+  // Test error handling code
+  await expect(functionThatLogs()).rejects.toThrow();
+
+  // Verify error was logged
+  expect(consoleErrorSpy).toHaveBeenCalledWith("Expected error:", expect.any(Error));
+
+  // Restore console.error
+  consoleErrorSpy.mockRestore();
+});
+```
+
+#### E2E Integration Testing for Cross-Platform Code
+For code that calls platform-specific system APIs (like Windows PowerShell or Linux notify-send), use helper functions that build the command structure without execution. This allows CI to verify cross-platform compatibility on Linux-only containers:
+
+```rust
+/// Build notify-send command for testing (doesn't execute)
+#[cfg(test)]
+fn build_notify_send_command(title: &str, body: &str) -> (String, Vec<String>) {
+    (
+        "notify-send".to_string(),
+        vec![
+            title.to_string(),
+            body.to_string(),
+            "--urgency=normal".to_string(),
+            "--app-name=Hikari Desktop".to_string(),
+        ],
+    )
+}
+
+#[test]
+fn test_e2e_notify_send_command_structure() {
+    let (command, args) = build_notify_send_command("Test Title", "Test Body");
+
+    assert_eq!(command, "notify-send");
+    assert_eq!(args.len(), 4);
+    assert_eq!(args[0], "Test Title");
+    assert_eq!(args[1], "Test Body");
+}
+```
+
+This approach:
+- Verifies command structure, argument order, and escaping logic
+- Tests cross-platform code paths without requiring the target platform
+- Allows CI to catch regressions in Windows-specific code whilst running on Linux
+- Keeps tests fast and deterministic (no actual system calls)
 
 ### Example Test Structure
 
@@ -71,6 +127,17 @@ describe("FeatureName", () => {
 });
 ```
 
+### Adding Tests for New Features
+
+When developing new features, always add corresponding tests:
+
+1. **Before implementing**: Consider what needs testing (happy path, edge cases, errors)
+2. **During implementation**: Write tests alongside the code
+3. **After implementation**: Run `pnpm test:coverage` to verify coverage remains high
+4. **Before committing**: Ensure `check-all.sh` passes (includes all tests)
+
+The goal is to maintain our near-100% coverage as the codebase grows, so future refactoring and changes can be made with confidence!
+
 ## Project Context
 
 Hikari Desktop is a Tauri-based desktop application that wraps Claude Code with a visual anime character (Hikari) who appears on screen. This is a personal project where Hikari can sign her work and act as herself!