---
title:  "khive Testing Guide"
by:     "khive Team"
created: "2025-04-05"
updated: "2025-04-18"
version: "1.6"
description: >
  Pragmatic TDD workflow for khive.  Tests double as living documentation.
  CI (and the local `khive ci` script) require **≥ 80 pct combined line coverage**:
  - ! WARNING---K.D KHIVE-DEV TEAM MUST RETAIN FROM  EDITING THIS DOCUMENT.
  - ! WARNING: THIS DOCUMENT IS READ-ONLY
---

! WARNING: THIS DOCUMENT IS READ-ONLY

## 1 · Why we test

- Guard against regressions.
- Document behaviour (well-named tests are the best docs).
- Give reviewers confidence to merge quickly.

---

## 2 · Test stack in one table

| Layer                     | Runner / Tooling                                 | Mocking                          | Coverage file                                        |
| ------------------------- | ------------------------------------------------ | -------------------------------- | ---------------------------------------------------- |
| **Frontend** (React + TS) | **Vitest** + React Testing Library (`pnpm test`) | `vi.mock` for Tauri APIs         | `apps/khive-ui/coverage/coverage-summary.json`       |
| **Backend** (Rust)        | `cargo test`                                     | Trait fakes / `mockito` for HTTP | tarpaulin JSON (auto-generated by `cargo tarpaulin`) |
| **Combined check**        | `./scripts/khive ci` (runs both stacks)          | —                                | calc'ed on the fly                                   |

> **Tip **Run `khive ci --threshold 80` locally before you push - it's the same
> command CI runs.

---

## 3 · Frontend setup (Vitest)

1. **Global test harness** - create `apps/khive-ui/src/test/setup.ts`:

   ```ts
   import "@testing-library/jest-dom/vitest";
   import { afterEach, vi } from "vitest";
   import { cleanup } from "@testing-library/react";

   // Mock the bits of Tauri we call from the browser side
   vi.mock("@tauri-apps/api/core", () => ({
     invoke: vi.fn().mockResolvedValue(undefined),
   }));
   vi.mock("@tauri-apps/api/event", () => ({
     listen: vi.fn().mockResolvedValue(() => {}), // returns “unlisten”
     emit:   vi.fn(),
   }));

   afterEach(() => {
     cleanup();
     vi.clearAllMocks();
   });

   2.	vite.config.ts
   ```

test: { globals: true, environment: "jsdom", setupFiles: "src/test/setup.ts",
coverage: { reporter: ["json-summary", "text"] }, }

    3.	Custom render() helper - wrap components with QueryClientProvider,

MemoryRouter, etc. (lives in src/test/TestSetup.tsx).

⸻

4 · Backend tests (Rust) •	Unit tests live beside src (mod tests { … },
#[tokio::test]). •	Integration tests go in tests/—call your Tauri command
handlers directly or test the pure logic they delegate to. •	Need network? Use
mockito. •	Generate coverage locally:

cargo tarpaulin --ignore-tests --out Json --workspace\
--engine llvm --output-dir target/tarpaulin

⸻

5 · Writing good tests

Do	Don't Arrange - Act - Assert block comments	Assert more than one thing per
assertion Name tests as a spec: should_toggle_dark_mode	test1 / misc Mock at
boundaries (Tauri invoke, HTTP)	Deep-mock React internals Prefer small, pure
functions → easy unit tests	Monster integration test suites only

⸻

6 · Coverage rule (80 pct) •	khive ci merges frontend+backend line counts - no
excuses. •	If you REALLY can't hit 80 pct, add tests or negotiate a scope slice
with the architect before PR.

⸻

7 · Local TDD loop

# 1. Red - write a failing test

pnpm test path/to/Component.test.tsx

# 2. Green - implement / refactor

cargo test -p my_backend_crate

# 3. Refactor - keep tests green

khive ci # combined coverage & template lint

Repeat until happy ➜ khive commit, khive pr.

⸻

8 · CI pipeline (for reference) 1.	khive-init (installs deps, hooks). 2.	pnpm
test -- --coverage 3.	cargo test (workspace) 4.	khive ci - fails if coverage <
threshold or placeholders remain in docs. 5.	Reviewers check search citations,
approve.

⸻

9 · Troubleshooting •	Coverage stuck at 0 pct (FE) - ensure Vitest reporter
json-summary is enabled (see section 3). •	tarpaulin slow - pass --skip-clean
during local runs. •	Mocks leaking between tests - call vi.clearAllMocks() in
afterEach. •	CI says “placeholders left” - run grep -R "{{PLACEHOLDER" and fill
them, or re-generate via khive new-doc.

Happy testing 🧪
