testing-patterns

Testing Patterns

TypeScript / JavaScript Testing (Vitest)

File Conventions

Colocated tests: src/foo.test.ts next to src/foo.ts (primary pattern)
E2E tests: *.e2e.test.ts in test/ directory or colocated
Live tests: *.live.test.ts for tests requiring real API keys
Setup file: test/setup.ts for global beforeEach/afterEach hooks
Config layering: base vitest.config.ts extended by vitest.unit.config.ts, vitest.e2e.config.ts, vitest.live.config.ts

Test Structure

import { describe, expect, it, vi } from "vitest";

describe("resolvePermission", () => { it("auto-approves safe tools without prompting", async () => { const prompt = vi.fn(async () => true); const res = await resolvePermission(makeRequest(), { prompt }); expect(res).toEqual({ outcome: "allow" }); expect(prompt).not.toHaveBeenCalled(); });

it("prompts for dangerous operations", async () => { const prompt = vi.fn(async () => true); await resolvePermission(makeDangerousRequest(), { prompt }); expect(prompt).toHaveBeenCalledTimes(1); expect(prompt).toHaveBeenCalledWith("exec", "exec: rm -rf /"); }); });


### Mock Patterns
```typescript
// Function mocks for dependency injection
const sendFn = vi.fn(async () => ({ messageId: "test" }));

// Module mocks (use sparingly -- prefer DI)
vi.mock("./network.js", () => ({
  fetch: vi.fn().mockResolvedValue({ ok: true }),
}));

// Spy on existing methods
const spy = vi.spyOn(store, "save");
expect(spy).toHaveBeenCalledWith(expectedData);

// Stub environment variables (auto-cleaned with unstubEnvs: true)
vi.stubEnv("API_KEY", "test-key-123");

// Fake timers (guard against leaks in afterEach)
vi.useFakeTimers();
vi.advanceTimersByTime(5000);
// Always restore: vi.useRealTimers()

Test Setup Pattern (Global)

// test/setup.ts
import { afterAll, afterEach, beforeEach, vi } from "vitest";
import { withIsolatedTestHome } from "./test-env.js";

process.env.VITEST = "true";
const testEnv = withIsolatedTestHome(); // Isolated HOME per worker
afterAll(() => testEnv.cleanup());

afterEach(() => {
  if (vi.isFakeTimers()) vi.useRealTimers(); // Prevent cross-test leaks
});

Factory Functions for Test Data

// Prefer factory functions over raw object literals
function makePermissionRequest(
  overrides: Partial<PermissionRequest> = {},
): PermissionRequest {
  const base: PermissionRequest = {
    sessionId: "session-1",
    toolCall: { toolCallId: "tool-1", title: "read: src/index.ts", status: "pending" },
    options: [{ kind: "allow_once", optionId: "allow" }],
  };
  return { ...base, ...overrides };
}

Coverage Configuration

// vitest.config.ts
coverage: {
  provider: "v8",
  reporter: ["text", "lcov"],
  all: false, // Only count files exercised by tests
  thresholds: { lines: 70, functions: 70, branches: 55, statements: 70 },
  include: ["./src/**/*.ts"],
  exclude: ["src/**/*.test.ts", "src/cli/**", "src/gateway/**"],
}

Anti-Patterns

Do NOT set maxWorkers above 16 (diminishing returns, flaky on CI)
Do NOT test implementation details (internal state, private methods)
Do NOT use vi.mock when dependency injection via function params works
Do NOT leak fake timers across tests -- always restore in afterEach
Do NOT skip edge cases: empty input, null, boundary values, error paths

Rust Testing (cargo test)

File Conventions

Inline unit tests: #[cfg(test)] mod tests at the bottom of each source file (primary pattern)
Integration tests: tests/ directory at crate root (rare in workspace projects)
Test-only dependencies: in [dev-dependencies] of each crate's Cargo.toml
Run all: cargo test --lib | Single crate: cargo test -p claudio-gateway --lib
Filter by name: cargo test --lib test_name_substring
Skip slow tests: cargo test --lib -- --skip concurrent

Unit Test Structure

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::Duration;

    #[test]
    fn insert_and_get() {
        let map = BoundedMap::new(10, Duration::from_secs(60));
        assert!(map.insert("a", 1));
        assert_eq!(map.get("a"), Some(1));
    }

    #[test]
    fn capacity_enforced() {
        let map = BoundedMap::new(3, Duration::from_secs(60));
        map.insert("a", 1);
        map.insert("b", 2);
        map.insert("c", 3);
        map.insert("d", 4); // should evict one
        assert!(map.len() <= 3);
    }

    #[test]
    fn ttl_expiry_on_get() {
        let map = BoundedMap::new(10, Duration::from_millis(1));
        map.insert("a", 1);
        std::thread::sleep(Duration::from_millis(5));
        assert_eq!(map.get("a"), None);
    }
}

Async Tests

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::Arc;

    #[tokio::test]
    async fn returns_immediately_when_no_tool_calls() {
        let provider = Arc::new(MockToolProvider::new(vec![final_response("Hello!")]));
        let mut executor = AgentExecutor::new(provider, "http://unused:9999", 10);

        let result = executor.execute(test_request()).await.unwrap();
        assert_eq!(result.iterations, 1);
        assert_eq!(result.tool_calls_made, 0);
    }

    #[tokio::test]
    async fn max_iterations_produces_final_response() {
        // Provider always returns tool calls -- should hit max iterations
        let provider = Arc::new(MockToolProvider::new(vec![tool_call_response()]));
        let mut executor = AgentExecutor::new(provider, "http://unused:9999", 3);
        let result = executor.execute(test_request()).await.unwrap();
        assert!(result.iterations <= 3);
    }
}

Stub/Mock Providers (Trait-Based Mocking)

/// Stub: always returns a fixed response. No network calls.
pub struct StubProvider { provider_name: String }

#[async_trait]
impl Provider for StubProvider {
    fn name(&self) -> &str { &self.provider_name }
    async fn chat_completion(&self, req: &ChatCompletionRequest)
        -> Result<ChatCompletionResponse, ProviderError> {
        Ok(ChatCompletionResponse { /* canned fields */ })
    }
}

/// Scripted: returns pre-configured responses in sequence.
/// Useful for multi-turn agent loops.
pub struct ScriptedProvider {
    responses: std::sync::Mutex<Vec<ChatCompletionResponse>>,
}