How to Run Unit Tests in OpenWork: A Complete Testing Guide

Run unit tests in OpenWork using pnpm test commands defined in the root package.json, with specialized suites for health checks, sessions, events, and end-to-end testing.

OpenWork is an AI-powered workspace application built with pnpm workspaces. Understanding how to run unit tests in OpenWork ensures code quality across its modular architecture. This guide covers all test commands, their purposes, and the exact workflow used by the different-ai/openwork repository.

Test Command Overview

All test scripts reside in the root package.json in the "scripts" section. OpenWork uses pnpm exclusively—npm or yarn are not supported.

The repository defines granular test suites rather than a single monolithic command. This design lets developers run targeted tests during development or full suites in CI.

Available Test Scripts

OpenWork provides 14+ specialized test commands. Each targets specific functionality:

Command	Purpose
pnpm test:e2e	End-to-end tests for desktop and web UI
pnpm test:health	Basic sanity checks for the main app
pnpm test:sessions	Session creation, persistence, and cleanup
pnpm test:refactor	Refactoring safety validation
pnpm test:events	Internal event bus and listeners
pnpm test:todos	TODO-tracking utilities
pnpm test:permissions	Role-based access control
pnpm test:session-error-recovery	Recovery from crashed sessions
pnpm test:session-scope	Scoped data isolation per session
pnpm test:session-switch	Seamless session switching
pnpm test:fs-engine	Virtual filesystem abstraction
pnpm test:eval-runner	Core evaluation harness (evals folder)
pnpm test:admin-scale	Admin API scalability (Den backend)

Run any command from the repository root:

pnpm test:health

Step-by-Step Testing Workflow

1. Install Dependencies

pnpm install

This installs all workspace dependencies and dev tools including Vitest, the testing framework used throughout OpenWork.

2. Run Default Unit Tests

pnpm test

If test is defined as a shortcut, this runs the primary test suite. Check package.json to confirm which suites it chains together.

3. Run Specific Test Suites

# End-to-end tests (most comprehensive)

pnpm test:e2e

# Multiple suites in sequence

pnpm test:health && pnpm test:sessions && pnpm test:events

4. Full Development Testing

# Verify core functionality before committing

pnpm test:health
pnpm test:refactor
pnpm test:e2e

Environment Requirements

Some test suites require external services. The package.json scripts handle container orchestration automatically, but manual runs need setup.

Required Services by Test Suite

Test Suite	Required Service	Setup Command
test:admin-scale	MySQL	pnpm dev:den:mysql
Den-related tests	Docker containers	scripts/dev-local.mjs

Environment Variables

Key variables defined in package.json scripts:

• DATABASE_URL — MySQL connection string
• DEN_DB_ENCRYPTION_KEY — Encryption for Den backend

Defaults are safe for local development. Production deployments require explicit configuration.

Key Test Files and Directories

Understanding the repository structure helps when debugging test failures:

• package.json — All test commands and environment defaults
• scripts/dev-local.mjs — Local Den service orchestration
• evals/runner/run.mjs — Evaluation framework runner
• packages/*/test/*.test.ts — Package-specific unit tests
• .opencode/*.test.ts — Example Vitest implementations showing framework patterns
• packaging/docker/docker-compose.web-local.yml — MySQL container for Den tests

Running Tests in CI

For continuous integration, chain commands explicitly rather than relying on shortcuts:

#!/bin/bash
set -e

pnpm install --frozen-lockfile
pnpm test:health
pnpm test:refactor
pnpm test:permissions
pnpm test:e2e

The --frozen-lockfile flag ensures reproducible builds. The set -e directive fails fast on any test suite error.

Debugging Test Failures

When unit tests in OpenWork fail:

1. Check service status — Run docker ps to verify MySQL or other containers are active
2. Review logs — Vitest outputs detailed stack traces to stderr
3. Isolate the suite — Run single test files: pnpm vitest run packages/core/test/sessions.test.ts
4. Reset environment — pnpm clean and reinstall if state corruption suspected

Summary

• OpenWork uses pnpm with 14+ specialized test commands in package.json
• Run pnpm test:health and pnpm test:e2e for core validation
• Some suites need Docker services started via dev:den:mysql or scripts/dev-local.mjs
• Tests are implemented in Vitest with files at packages/*/test/*.test.ts

Frequently Asked Questions

What testing framework does OpenWork use?

OpenWork uses Vitest for all unit and integration testing. Evidence appears in .opencode/* test files and the packages/*/test/*.test.ts patterns throughout the repository. The framework provides fast execution with native TypeScript support.

Can I run tests without Docker?

Yes for most suites. Health checks, refactor tests, session tests, and event tests run without containers. However, test:admin-scale and other Den-backend suites require MySQL via Docker. Run pnpm dev:den:mysql first to start the container.

Where are the actual test files located?

Test implementations follow the pattern packages/[package-name]/test/*.test.ts. The evaluation runner lives at evals/runner/run.mjs. Example Vitest patterns appear in .opencode/*.test.ts files for reference.

How do I add a new test suite?

Add a script entry to package.json following the test:[name] naming convention. Create corresponding test files in the appropriate packages/[name]/test/ directory. Follow existing patterns in packages/core/test/ for consistency with OpenWork's testing conventions.

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