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

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.

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 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 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 – scripts.test
pnpm evals:test	Execute OpenWork test-kit specs under evals/	package.json – scripts.evals:test
pnpm evals:spec	Generate and run specification-driven e2e tests	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:

pnpm --filter @openwork/app test:e2e

Step-by-Step Testing Workflows

Initial Setup

Install dependencies once after cloning the repository:

pnpm install

Run Complete Test Matrix

For CI pipelines or pre-commit validation:

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:

pnpm test:e2e

Single package testing (headless-web launcher example):

pnpm --filter @openwork/app test

Official spec verification workflow:

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 tests the headless-web launcher

Desktop UI Tests

• Location: packages/app/src/**/*.test.ts
• Architecture docs: 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	Central script definitions and workspace configuration
scripts/dev-headless-web.test.ts	Example unit test for headless-web launcher
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.

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