How to Run Tests in the Kaneo Monorepo: Unit and Integration Testing Guide

Run unit tests with pnpm test and integration tests with pnpm test:integration after setting up a PostgreSQL instance and configuring DATABASE_URL in your environment.

Kaneo is a TurboRepo-driven monorepo for project management that uses Vitest as its test runner. The testing infrastructure supports both fast unit tests without database dependencies and comprehensive integration tests that exercise the full backend stack against a real PostgreSQL instance. This guide covers the complete workflow for running tests in Kaneo based on the source code at usekaneo/kaneo.

Prerequisites

Before running tests, ensure your environment meets these requirements:

• Node.js >= 18
• pnpm >= 10
• Docker (optional but recommended for PostgreSQL)

The integration test suite specifically requires a running PostgreSQL server on port 5432. According to ENVIRONMENT_SETUP.md, "for any backend test or integration tests you must have a PostgreSQL instance running and expose the port 5432 to the host environment so the test runner can connect to it."

Environment Configuration

1. Install Dependencies

git clone https://github.com/usekaneo/kaneo.git
cd kaneo
pnpm install

2. Configure Environment Variables

Create a .env file at the repository root. For integration tests, you must provide a valid DATABASE_URL:

DATABASE_URL=postgres://postgres:password@localhost:5432/kaneo_test
AUTH_SECRET=your-secret-key-here

3. Start PostgreSQL (for Integration Tests)

The quickest approach uses Docker:

docker run -d -p 5432:5432 \
  --name kaneo-pg \
  -e POSTGRES_PASSWORD=password \
  postgres:16-alpine

In tests/api-integration/setup.ts, the test harness explains: "These tests require a PostgreSQL instance. Set the environment variable DATABASE_URL to point to your local DB. For CI it uses the default postgres user."

How to Run Unit Tests in Kaneo

Unit tests execute without database dependencies and cover individual packages across the monorepo.

Run All Unit Tests

pnpm test

This command triggers Turborepo to run test suites in parallel across all packages. The root package.json defines this script to delegate to each workspace's Vitest configuration.

Run Package-Specific Unit Tests

Command	Target
pnpm --filter @kaneo/api test	API/backend logic only
pnpm --filter @kaneo/web test	Frontend component tests
pnpm --filter @kaneo/app test	Desktop application tests

Watch Mode for Development

pnpm test -- --watch

This re-runs affected tests on file changes, useful for test-driven development.

How to Run Integration Tests in Kaneo

Integration tests verify end-to-end behavior with real database operations.

Execute the Full Integration Suite

pnpm test:integration

In tests/api-integration/helpers/database.ts, the helper function "starts a fresh PostgreSQL database for tests" by creating a database named with the process ID, ensuring test isolation. The helper requires "a running PostgreSQL server listening on the default port 5432 and a user postgres with a password (or no password if you have configured trust authentication)."

Run a Single Integration Test File

pnpm vitest run tests/api-integration/workspace-rbac.test.ts

Test Configuration Architecture

Kaneo uses separate Vitest configurations for different test types:

Configuration File	Purpose
apps/api/vitest.config.ts	Unit test settings
apps/api/vitest.integration.config.ts	Integration test settings with database setup

The integration configuration imports from tests/api-integration/setup.ts, which orchestrates the global beforeAll and afterAll hooks for database lifecycle management.

Complete Code Examples

Development Workflow

# Terminal 1: Start PostgreSQL

docker run -d -p 5432:5432 \
  --name kaneo-pg \
  -e POSTGRES_PASSWORD=password \
  postgres:16-alpine

# Terminal 2: Run tests

cd /path/to/kaneo

# Fast feedback loop - unit tests only

pnpm test -- --watch

# Before committing - full validation

pnpm test
pnpm test:integration

CI Pipeline Example

#!/bin/bash

# .github/workflows/test.yml equivalent

# Start services

docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16-alpine

# Install and test

pnpm install
pnpm test
DATABASE_URL=postgres://postgres:postgres@localhost:5432/kaneo_test pnpm test:integration

Key Source Files Reference

File Path	Description
package.json (root)	Defines test and test:integration scripts
tests/api-integration/setup.ts	Global test setup, PostgreSQL requirements documentation
tests/api-integration/helpers/database.ts	Database creation helper with process ID isolation
tests/api-integration/helpers/auth.ts	Server startup utilities for integration tests
apps/api/vitest.config.ts	Unit test runner configuration
apps/api/vitest.integration.config.ts	Integration test runner configuration

Summary

• Unit tests (pnpm test) run without external dependencies and validate individual modules through Turborepo's parallel execution
• Integration tests (pnpm test:integration) require PostgreSQL on port 5432 and exercise the complete backend stack with real database transactions
• Database isolation in integration tests is achieved through process-specific database names created by tests/api-integration/helpers/database.ts
• Package-specific filtering uses pnpm's --filter flag with workspace names like @kaneo/api and @kaneo/web

Frequently Asked Questions

Why do my integration tests fail with "connection refused"?

Your DATABASE_URL environment variable is misconfigured or PostgreSQL is not running on port 5432. Verify with docker ps that your container is healthy, then check that your .env file contains a valid connection string pointing to localhost.

Can I run tests without Docker?

Yes for unit tests, no for integration tests. Unit tests execute entirely in Vitest with mocked dependencies. Integration tests specifically require a PostgreSQL instance that the helper in tests/api-integration/helpers/database.ts can connect to and create databases on.

How does Kaneo isolate test databases between runs?

The database helper in tests/api-integration/helpers/database.ts generates unique database names using the Node.js process ID: kaneo_test_${process.pid}. This prevents collisions when running tests in parallel or across multiple terminals.

What's the difference between pnpm test and pnpm vitest run?

pnpm test invokes Turborepo's task runner across all packages with proper caching and parallelization. pnpm vitest run executes Vitest directly in the current directory without monorepo orchestration. Use the former for full validation and the latter for targeted debugging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}