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

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 (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 and apps/api/vitest.integration.config.ts respectively. The Turbo configuration in 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:

# 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:

# Install all workspace dependencies

pnpm install

3. Execute Unit Tests

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

# 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 ensures dependent packages build before tests execute.

4. Execute Integration Tests

For integration testing against a real database:

# 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: Defines the test and test:integration npm scripts at lines 5-16 that invoke TurboRepo tasks.
• turbo.json: Configures the test and test:integration tasks, their dependencies, and output locations at lines 27-36.
• apps/api/vitest.config.ts: Configures Vitest for unit tests, including coverage settings and global variables.
• apps/api/vitest.integration.config.ts: Handles database connections and environment setup specific to integration testing.
• tests/api/label/delete-label.test.ts: Example unit test demonstrating API layer testing patterns.
• 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 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 (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 for unit tests and 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 (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 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 and ensures all required build steps complete first, providing consistent results across the entire monorepo.

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