How to Run Kaneo API Tests: Unit and Integration Guide

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.

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.

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 file that orchestrates the required services.

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:

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:

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.

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:

pnpm test:integration

Alternatively, target the API package explicitly:

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.

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 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 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.

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