# How to Run Tests in the Kaneo Repository: A Complete Guide

> Learn how to run tests in the Kaneo repository easily. This guide covers unit and integration tests using pnpm and TurboRepo, ensuring a smooth development workflow. Get started now!

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

---

**The Kaneo monorepo uses pnpm and TurboRepo to orchestrate its test suites, requiring only `pnpm install` followed by `pnpm test` for unit tests or `pnpm test:integration` for integration tests after configuring your environment variables.**

The Kaneo project is a TypeScript monorepo that leverages modern JavaScript tooling to manage its testing workflow. To effectively run tests in the Kaneo repository, you need to understand how **pnpm** workspaces and **TurboRepo** tasks interact with the **Vitest** test runner. This guide walks through the exact commands, configuration files, and environment setup required to execute both unit and integration test suites.

## Prerequisites: Environment Configuration

Before executing any test commands, you must configure the environment variables that Kaneo expects. Create an `.env` file in the project root (or copy from `.env.example` if available) and define required variables such as `DATABASE_URL`, `KANEO_API_URL`, and credentials for PostgreSQL and Redis.

The integration test suite located in `tests/api-integration/**` spins up a real PostgreSQL instance, so ensure your `DATABASE_URL` points to a valid database server. Additional variables like `POSTGRES_*` and `REDIS_URL` are necessary for the full integration suite to function correctly.

## Understanding the Test Architecture

The Kaneo repository delegates test execution to **TurboRepo**, which caches and parallelizes tasks across the monorepo. According to the source code in the root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) (lines 5-16), the project defines two primary npm scripts: `test` for unit-style tests and `test:integration` for the full integration suite. These scripts invoke TurboRepo tasks that automatically build dependent packages before running tests.

The underlying test runner is **Vitest**, with separate configurations for unit and integration contexts in [`apps/api/vitest.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.config.ts) and [`apps/api/vitest.integration.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.integration.config.ts) respectively. The Turbo configuration in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) (lines 27-36) declares the test tasks, their dependencies, and output locations.

## Step-by-Step Testing Workflow

### 1. Configure Environment Variables

Copy the example environment file and customize it for your local setup:

```bash

# Set up environment variables (copy from .env.example if available)

cp .env.example .env   # then edit .env as needed

```

Ensure values for `DATABASE_URL`, `KANEO_API_URL`, and other PostgreSQL credentials are valid before proceeding to integration tests.

### 2. Install Dependencies

Install all packages across the monorepo using pnpm. This resolves workspace packages and installs the Vitest test runner:

```bash

# Install all workspace dependencies

pnpm install

```

### 3. Execute Unit Tests

Run the unit test suite using the root-level npm script:

```bash

# Run the unit-test suite

pnpm test

# → executes `turbo test`, runs all tests under tests/api/**

```

This command runs `turbo test`, which executes all test files under `tests/api/**` and reports coverage to the `coverage/` directory. The task configuration in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) ensures dependent packages build before tests execute.

### 4. Execute Integration Tests

For integration testing against a real database:

```bash

# Run the integration-test suite (requires PostgreSQL)

pnpm test:integration

# → executes `turbo test:integration`, runs tests under tests/api-integration/**

```

This runs `turbo test:integration`, executing the test suite located in `tests/api-integration/**`. These tests require a running PostgreSQL server and validate the full stack including database operations and authentication flows.

## Key Configuration Files

Understanding these specific source files helps when debugging test failures or extending test coverage:

- **Root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json)**: Defines the `test` and `test:integration` npm scripts at lines 5-16 that invoke TurboRepo tasks.
- **[`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json)**: Configures the `test` and `test:integration` tasks, their dependencies, and output locations at lines 27-36.
- **[`apps/api/vitest.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.config.ts)**: Configures Vitest for unit tests, including coverage settings and global variables.
- **[`apps/api/vitest.integration.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.integration.config.ts)**: Handles database connections and environment setup specific to integration testing.
- **[`tests/api/label/delete-label.test.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api/label/delete-label.test.ts)**: Example unit test demonstrating API layer testing patterns.
- **[`tests/api-integration/workspace-rbac.test.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/workspace-rbac.test.ts)**: Sample integration test exercising workspace role-based access control with full database interaction.

## Summary

- The Kaneo repository uses **pnpm** with **TurboRepo** to orchestrate tests across its monorepo structure according to the root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) configuration.
- **Unit tests** reside in `tests/api/**` and run via `pnpm test`, which delegates to `turbo test` and outputs coverage to `coverage/`.
- **Integration tests** in `tests/api-integration/**` run via `pnpm test:integration` and require a running PostgreSQL instance with valid `DATABASE_URL` and `POSTGRES_*` environment variables.
- Both commands leverage the task definitions in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) (lines 27-36) to automatically handle dependency builds and caching.
- Vitest configurations in `apps/api/` separate unit testing concerns from integration testing contexts that require database connectivity.

## Frequently Asked Questions

### What test runner does the Kaneo repository use?

The Kaneo repository uses **Vitest** as its test runner. The configuration is split between [`apps/api/vitest.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.config.ts) for unit tests and [`apps/api/vitest.integration.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vitest.integration.config.ts) for integration tests, allowing different setups for isolated unit testing versus full-stack integration testing with database connections.

### Why does `pnpm test:integration` fail with database connection errors?

Integration tests require a running PostgreSQL server and valid `DATABASE_URL` in your `.env` file. Unlike unit tests in `tests/api/**`, the integration suite in `tests/api-integration/**` exercises real database operations. Ensure your environment variables include correct `POSTGRES_*` credentials and that the database server is accessible before running this command.

### How does TurboRepo improve the testing workflow in Kaneo?

TurboRepo caches test results and automatically builds dependent packages before running tests. As configured in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) (lines 27-36), the `test` and `test:integration` tasks define their outputs and dependencies, ensuring that code changes trigger only the necessary rebuilds and test reruns. This significantly speeds up subsequent test executions across the monorepo.

### Can I run tests for a specific workspace package only?

While the root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) scripts run all tests via TurboRepo, you can navigate to specific workspace directories and run pnpm test commands directly. However, using `pnpm test` from the root is recommended as it respects the dependency graph defined in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) and ensures all required build steps complete first, providing consistent results across the entire monorepo.