# How to Run Kaneo API Tests: Unit and Integration Guide

> Learn to run Kaneo API tests efficiently. Execute Vitest unit tests with pnpm test or integration tests with pnpm test:integration for comprehensive API validation.

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

---

**Execute `pnpm test` to run fast unit tests with Vitest, or `pnpm test:integration` to run full-stack integration tests against a live PostgreSQL database.**

Kaneo is an open-source project management platform built as a pnpm monorepo managed by Turborepo. Understanding how to run Kaneo API tests ensures you can validate changes to the backend logic before deployment. This guide covers both the lightweight unit test suite and the comprehensive integration tests that verify database interactions and HTTP endpoints.

## Prerequisites for Running Kaneo API Tests

### Install Monorepo Dependencies

The repository uses a single lock file at the root, so one command installs all workspace dependencies.

```bash
pnpm install

```

### Configure Test Environment Variables

Copy the example environment file to create your test configuration. This file defines `DATABASE_URL` and other variables required for integration testing.

```bash
cp .env.test.example .env.test

```

The `.env.test.example` file contains sensible defaults, but you can modify values in `.env.test` if you need custom database connection strings.

### Start PostgreSQL with Docker

Integration tests require a running PostgreSQL instance. The repository includes a [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) file that orchestrates the required services.

```bash
docker compose -f compose.yml up -d db

```

This command starts the database container in detached mode, providing the persistent storage layer that integration tests expect.

### Prepare the Database Schema (Optional)

While the API automatically runs migrations on startup, you can manually generate and apply them:

```bash
pnpm --filter @kaneo/api db:generate
pnpm --filter @kaneo/api db:migrate

```

## Running Unit Tests in Kaneo

Unit tests provide fast feedback by testing individual modules without external services. In the Kaneo codebase, unit tests live alongside source files in `apps/api/**/*.test.*` and use Vitest as the test runner.

To execute the unit test suite across the entire monorepo:

```bash
pnpm test

```

This command invokes Turborepo's `test` pipeline, which delegates to each workspace's `test` script. For the API package specifically, this runs Vitest against files like [`apps/api/src/project/controllers/create-project.test.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/project/controllers/create-project.test.ts).

## Running Integration Tests in Kaneo

Integration tests validate complete HTTP workflows against a real database. Located in `tests/api-integration/**/*.test.ts`, these tests spin up the API server and execute scenarios such as project creation, task handling, and billing enforcement.

To run the full integration suite:

```bash
pnpm test:integration

```

Alternatively, target the API package explicitly:

```bash
pnpm --filter @kaneo/api test:integration

```

The integration test suite connects to the Docker-provided PostgreSQL container defined in your `.env.test` file, ensuring realistic data persistence behavior. You can examine specific test implementations in files like [`tests/api-integration/project.test.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/project.test.ts).

## How Kaneo API Tests Work in CI

The repository's continuous integration pipeline validates all changes using the same commands described above. The workflow definition in [`.github/workflows/ci.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/ci.yml) executes both `pnpm test` and `pnpm test:integration` to ensure code quality. Reviewing this file shows how the project maintains test consistency between local development and automated builds.

## Summary

- **Use `pnpm test`** to execute fast unit tests with Vitest that require no external services.
- **Use `pnpm test:integration`** to run end-to-end tests against a live PostgreSQL database spun up via Docker Compose.
- **Configure environment variables** by copying `.env.test.example` to `.env.test` before running integration tests.
- **Locate test files** in `apps/api/` for unit tests and `tests/api-integration/` for integration scenarios.
- **Reference the CI pipeline** in [`.github/workflows/ci.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/ci.yml) to understand the official test execution process.

## Frequently Asked Questions

### What is the difference between unit and integration tests in Kaneo?

Unit tests are fast, isolated tests that run with Vitest and verify individual functions without database connections. Integration tests located in `tests/api-integration/` spin up the full API server and PostgreSQL database to validate complete HTTP request flows and data persistence.

### Do I need Docker to run Kaneo API tests?

You only need Docker for integration tests, which require a running PostgreSQL instance via `docker compose -f compose.yml up -d db`. Unit tests run entirely in memory and do not require external services or containers.

### How do I run tests for only the API package without the entire monorepo?

Use the `--filter` flag with pnpm to target the `@kaneo/api` package specifically. For unit tests, run `pnpm --filter @kaneo/api test`. For integration tests, use `pnpm --filter @kaneo/api test:integration`. This avoids running tests for other workspaces like the web client.

### Where are the test environment variables defined?

Test environment variables are defined in `.env.test`, which you create by copying `.env.test.example` at the repository root. This file specifies the `DATABASE_URL` and other secrets required for integration testing, while unit tests typically rely on default or mocked configurations.