Testing

This guide covers how to write and run tests for InnoClaw.

Test Framework

InnoClaw uses Vitest (v4+) as its test framework, configured in vitest.config.ts.

Configuration

// vitest.config.ts
import { defineConfig } from "vitest/config";
import path from "path";

export default defineConfig({
  test: {
    // Test file patterns
    include: ["src/**/*.test.{ts,tsx}"],
  },
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

Running Tests

# Run all tests
npm test

# Run tests with Vitest directly
npx vitest run

# Run tests in watch mode (re-runs on file changes)
npx vitest

# Run a specific test file
npx vitest run src/lib/rag/chunker.test.ts

# Run tests matching a pattern
npx vitest run --grep "should chunk text"

Writing Tests

Test File Location

Test files should be co-located with the source files they test:

src/
├── lib/
│   ├── rag/
│   │   ├── chunker.ts
│   │   └── chunker.test.ts    # Tests for chunker.ts
│   └── utils/
│       ├── helpers.ts
│       └── helpers.test.ts    # Tests for helpers.ts

Test Structure

import { describe, it, expect } from "vitest";
import { myFunction } from "./my-module";

describe("myFunction", () => {
  it("should return expected result", () => {
    const result = myFunction("input");
    expect(result).toBe("expected output");
  });

  it("should handle edge cases", () => {
    expect(myFunction("")).toBe("");
    expect(myFunction(null)).toBeNull();
  });
});

Path Aliases

Use the @/ alias to import from the src/ directory:

import { someUtil } from "@/lib/utils/helpers";

Test Categories

Unit Tests

Test individual functions and modules in isolation:

npx vitest run src/lib/rag/

Integration Tests

Test interactions between modules (e.g., API routes with database):

npx vitest run src/app/api/

Production Artifact Gate

Run the authoritative production build with:

NEXT_TELEMETRY_DISABLED=1 npm run build

The build uses Webpack and automatically invokes npm run verify:standalone. The verifier requires the compiled authentication proxy and fails if .next/standalone contains runtime databases, active environment files, backups, application source, tests, documentation, or local scratch directories. New runtime state must stay outside the Docker build context. Only relax the verifier for an asset that the production runtime intentionally needs, and verify the resulting Docker image separately.

Best Practices

• Co-locate test files with source files (e.g., module.test.ts next to module.ts)
• Use descriptive names for test cases that explain expected behavior
• Test edge cases — empty inputs, null values, boundary conditions
• Mock external dependencies — API calls, file system operations
• Keep tests focused — each test should verify one specific behavior