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

> Learn to run unit and integration tests in the Kaneo monorepo with simple pnpm commands. Set up PostgreSQL and DATABASE_URL to get started.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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

```bash
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`:

```env
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:

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

```

In [`tests/api-integration/setup.ts`](https://github.com/usekaneo/kaneo/blob/main/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

```bash
pnpm test

```

This command triggers Turborepo to run test suites in parallel across all packages. The root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/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

```bash
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

```bash
pnpm test:integration

```

In [`tests/api-integration/helpers/database.ts`](https://github.com/usekaneo/kaneo/blob/main/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

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.config.ts) | Unit test settings |
| [`apps/api/vitest.integration.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.integration.config.ts) | Integration test settings with database setup |

The integration configuration imports from [`tests/api-integration/setup.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/setup.ts), which orchestrates the global `beforeAll` and `afterAll` hooks for database lifecycle management.

## Complete Code Examples

### Development Workflow

```bash

# 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

```bash
#!/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`](https://github.com/usekaneo/kaneo/blob/main/package.json) (root) | Defines `test` and `test:integration` scripts |
| [`tests/api-integration/setup.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/setup.ts) | Global test setup, PostgreSQL requirements documentation |
| [`tests/api-integration/helpers/database.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/helpers/database.ts) | Database creation helper with process ID isolation |
| [`tests/api-integration/helpers/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/helpers/auth.ts) | Server startup utilities for integration tests |
| [`apps/api/vitest.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.config.ts) | Unit test runner configuration |
| [`apps/api/vitest.integration.config.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.