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

> Learn to run unit tests in OpenWork with pnpm test commands. Explore specialized testing suites for health checks sessions events and end to end scenarios. A complete guide.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Run unit tests in OpenWork using `pnpm test` commands defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```bash
pnpm test:health

```

## Step-by-Step Testing Workflow

### 1. Install Dependencies

```bash
pnpm install

```

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

### 2. Run Default Unit Tests

```bash
pnpm test

```

If `test` is defined as a shortcut, this runs the primary test suite. Check [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) to confirm which suites it chains together.

### 3. Run Specific Test Suites

```bash

# 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

```bash

# 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```bash
#!/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.