# How to Run Tests in the OpenWork Monorepo: Complete Commands and Workflows Explained

> Master running tests in the OpenWork monorepo. Discover commands for full suite, e2e, and individual package testing using pnpm. Simplify your development workflow.

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

---

**Run all OpenWork tests with `pnpm test`, run UI-specific e2e tests with `pnpm test:e2e`, or target individual packages using `pnpm --filter <package>` scripts defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json).**

The OpenWork monorepo uses **pnpm workspaces** to organize multiple packages including a desktop application, server components, plugins, and evaluation utilities. All test commands originate from the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) and leverage pnpm's filter flag to scope execution to specific workspaces. This guide covers every available test script, file locations, and practical workflows for contributors.

## Core Test Commands in OpenWork

The root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) defines a comprehensive test matrix. Each script uses pnpm's `--filter` flag to target the relevant workspace, keeping builds fast and focused.

### Full Test Suite

| Script | Purpose | Implementation |
|--------|---------|----------------|
| `pnpm test` | Run **all** unit tests (excluding UI), then `evals` suite and spec runner | [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) – `scripts.test` |
| `pnpm evals:test` | Execute OpenWork test-kit specs under `evals/` | [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) – `scripts.evals:test` |
| `pnpm evals:spec` | Generate and run specification-driven e2e tests | [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) – `scripts.evals:spec` |

### Desktop UI-Specific Tests

| Script | Purpose |
|--------|---------|
| `pnpm test:e2e` | End-to-end tests for `@openwork/app` |
| `pnpm test:health` | Health-check tests for UI package |
| `pnpm test:sessions` | Session-handling logic tests |
| `pnpm test:refactor` | UI refactor-related tests |
| `pnpm test:events` | UI event-driven code path validation |
| `pnpm test:todos` | Todo-management functionality tests |
| `pnpm test:permissions` | Permission check verification |
| `pnpm test:session-error-recovery` | Session error recovery testing |
| `pnpm test:fs-engine` | Virtual file-system engine coverage |

### Backend and Scale Tests

| Script | Purpose |
|--------|---------|
| `pnpm test:admin-scale` | Scalability tests for `@openwork-ee/den-api` |

All scripts expand internally using the pnpm filter pattern. For example, `pnpm test:e2e` executes:

```bash
pnpm --filter @openwork/app test:e2e

```

## Step-by-Step Testing Workflows

### Initial Setup

Install dependencies once after cloning the repository:

```bash
pnpm install

```

### Run Complete Test Matrix

For CI pipelines or pre-commit validation:

```bash
pnpm test

```

This script sequentially executes:
- Unit tests across all workspaces (except `@openwork/app`)
- UI unit tests
- UI e2e suite via `test:e2e`
- Eval test runner for spec-driven verification

### Targeted Development Testing

**UI feature development:**

```bash
pnpm test:e2e

```

**Single package testing (headless-web launcher example):**

```bash
pnpm --filter @openwork/app test

```

**Official spec verification workflow:**

```bash
pnpm evals:spec

```

## Where OpenWork Tests Are Located

Understanding the file structure helps navigate failures and add new coverage.

### Unit Tests

- **Convention:** `*.test.ts` files co-located with source code
- **Example:** [`scripts/dev-headless-web.test.ts`](https://github.com/different-ai/openwork/blob/main/scripts/dev-headless-web.test.ts) tests the headless-web launcher

### Desktop UI Tests

- **Location:** `packages/app/src/**/*.test.ts`
- **Architecture docs:** [`packages/app/src/react-app/ARCHITECTURE.md`](https://github.com/different-ai/openwork/blob/main/packages/app/src/react-app/ARCHITECTURE.md) outlines smoke and e2e test layers

### Eval-Kit Specifications

- **Specs:** `evals/specs/**/*.test.ts` — specification-driven end-to-end scenarios
- **Runner:** `evals/runner/*.test.mjs` — low-level test harness implementation

## Key Source Files for Test Implementation

| File Path | Role |
|-----------|------|
| [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) | Central script definitions and workspace configuration |
| [`scripts/dev-headless-web.test.ts`](https://github.com/different-ai/openwork/blob/main/scripts/dev-headless-web.test.ts) | Example unit test for headless-web launcher |
| [`packages/app/src/react-app/ARCHITECTURE.md`](https://github.com/different-ai/openwork/blob/main/packages/app/src/react-app/ARCHITECTURE.md) | UI test layer documentation (smoke/e2e) |
| `evals/specs/**/*.test.ts` | Spec-driven test definitions |
| `evals/runner/*.test.mjs` | Custom test-kit runner implementation |

## Performance and Isolation Notes

The `pnpm --filter` flag ensures that:
- Only required workspaces are built before testing
- Test execution remains parallelizable across packages
- Cache invalidation stays scoped to modified dependencies

For the UI package specifically, the e2e suite runs in isolation from other packages' unit tests, preventing cross-contamination of test state.

## Summary

- **Run everything:** `pnpm test` from repository root
- **UI-specific testing:** `pnpm test:e2e`, `pnpm test:health`, `pnpm test:sessions`, and related granular scripts
- **Package isolation:** Use `pnpm --filter <package-name> <script>` for targeted execution
- **Spec-driven validation:** `pnpm evals:spec` runs the official OpenWork verification workflow
- **Source locations:** Unit tests follow `*.test.ts` convention; e2e specs live in `evals/specs/`

## Frequently Asked Questions

### What testing framework does OpenWork use?

OpenWork uses a **custom test-kit runner** for spec-driven tests located in `evals/runner/*.test.mjs`, alongside standard testing tools for individual package unit tests. The evals system is specifically designed for end-to-end verification of the OpenWork platform's behavior.

### How do I run tests for only one package in the monorepo?

Use **pnpm's filter flag**: `pnpm --filter <package-name> test`. For example, `pnpm --filter @openwork/app test` runs only the desktop UI package's unit tests. This avoids building unrelated workspaces and significantly speeds up iteration.

### Why does `pnpm test` exclude the UI package initially?

The UI package has **separate, granular test scripts** (`test:e2e`, `test:health`, `test:sessions`, etc.) due to its complexity and longer execution time. The root `test` script runs UI unit tests separately, then explicitly invokes `test:e2e`, ensuring comprehensive coverage without mixing execution contexts.

### What's the difference between `evals:test` and `evals:spec`?

**`pnpm evals:test`** executes existing OpenWork test-kit specs under `evals/specs/`. **`pnpm evals:spec`** generates and runs specification-driven end-to-end tests through the "spec" workflow, which validates platform behavior against formal requirements.