homeio

Current State

Vitest is configured in vitest.config.ts with Node as the default environment, V8 coverage, and co-located test discovery for **/*.test.ts and **/*.test.tsx. test/setup.ts mocks server-only, EventSource, and window.matchMedia.

PROJECT_AUDIT.md reports that no real tests were found; that statement is stale. The suite now holds 220 test files and 1016 tests covering route handlers, server modules, the desktop shell and components, co-located in __tests__/ directories, and both npm run test and npm run test:coverage pass on main. Coverage writes lcov plus a text summary to ./coverage; it is reported, not gated. V8 instrumentation roughly doubles the runtime of the heaviest desktop renders, so vitest.config.ts raises testTimeout above the Vitest default — change the timeout there if a slow test ever needs more room.

Commands

npm run test
npm run test:watch
npm run test:coverage
npm run lint

Unit Test Pattern: Server Module

Place tests beside the module:

lib/server/modules/files/__tests__/path-resolver.test.ts
lib/server/modules/docker/__tests__/compose-runner.test.ts

Use direct imports, mock external process/network boundaries, and verify domain errors rather than string-matching logs.

Example structure:

import { describe, expect, it } from "vitest";
import { nextCronRun } from "@/lib/server/modules/scheduled-tasks/cron";

describe("nextCronRun", () => {
  it("returns the next run time", () => {
    expect(nextCronRun("0 2 * * *", new Date("2026-05-01T00:00:00Z"))).toBeTruthy();
  });
});

Component Test Pattern

Use React Testing Library for component behavior. Existing examples include modules/shell/components/__tests__/dock.test.tsx and page tests under app/login/__tests__/.

import { render, screen } from "@testing-library/react";
import { describe, expect, it } from "vitest";

describe("ComponentName", () => {
  it("renders the expected control", () => {
    render(<ComponentName />);
    expect(screen.getByRole("button")).toBeInTheDocument();
  });
});

Route Test Pattern

Route tests live beside route files:

app/api/v1/system/metrics/__tests__/route.test.ts
app/api/v1/store/apps/[appId]/install/__tests__/route.test.ts

Import GET, POST, etc. directly, construct NextRequest or Request, and mock server services.

High-Priority Coverage Areas

• lib/server/modules/docker/compose-runner.ts: brittle YAML/text transforms and Docker CLI calls.
• lib/server/modules/apps/operations.ts: operation state machine, async progress, failure cleanup.
• lib/server/modules/files/service.ts: path handling, write conflicts, trash, upload behavior.
• SSE routes: heartbeat, abort cleanup, and unauthorized 401 behavior.
• Auth route brute-force/rate-limit behavior in app/api/auth/login/__tests__/route.test.ts.
• Architecture route-auth guard in app/api/v1/__tests__/auth-architecture.test.ts.
• D-Bus helper protocol: services/dbus-helper/__tests__/protocol.test.ts should expand with new helper methods.

Coverage Targets

Use these as practical targets, not current guarantees:

• Server modules touched by a PR: meaningful unit tests for success and failure paths.
• API routes touched by a PR: route tests for auth, validation, success, and domain errors.
• Risky host actions: tests must cover guardrails and rejected input.
• UI changes: component tests for stateful controls and critical rendering.