How to Run Unit Tests for OpenWork: Complete Developer Guide

Install dependencies with pnpm install, then execute pnpm test to run all unit tests across the monorepo, or use pnpm --filter @openwork/app test to target specific workspace packages.

OpenWork is an open-source desktop automation platform maintained by different-ai that organizes its codebase as a pnpm workspace monorepo. Knowing how to run unit tests for OpenWork is essential for validating changes to the core libraries, headless threads, or the Electron desktop application without introducing regressions.

Install Dependencies

Before executing any test commands, install the workspace dependencies from the repository root. This pulls in all required testing utilities and dev dependencies defined across the monorepo packages.

pnpm install

Run the Complete Unit Test Suite

The primary command for continuous integration and local validation is pnpm test. According to the source code in the root [package.json](https://github.com/different-ai/openwork/blob/dev/package.json), this script chains together three distinct testing phases:

1. Recursive unit tests – Runs test scripts in every workspace package except @openwork/app and openwork-server
2. Evaluation suite unit tests – Executes tests under dev/evals/specs
3. PR validation tests – Runs additional checks for the evaluation framework

pnpm test

The actual script definition filters out the heavy UI components to keep the core logic tests fast:

"test": "pnpm -r --if-present --filter '!@openwork/app' --filter '!openwork-server' run test && pnpm --dir evals run test && pnpm --dir evals run test:pr"

Run Tests for Specific Packages

When debugging a specific module, use pnpm's --filter flag to limit execution to a single workspace package. This significantly reduces test duration and narrows console output to relevant failures.

Run the desktop application unit tests:

pnpm --filter @openwork/app test

Run the headless-threads package tests:

pnpm --filter @openwork/headless-threads test

You can apply this pattern to any workspace package defined in the monorepo, such as enterprise-mcp-mock-server or diagnostics.

Execute End-to-End Tests

The E2E suite validates the full Electron application, Den runtime, and UI integrations. Execute the complete suite with:

pnpm test:e2e

To run a single E2E specification file instead of the entire suite, append the file path after a double dash:

pnpm --filter @openwork/app test:e2e -- dev/evals/specs/workspace-new-task-hit-target.e2e.test.ts

Individual spec files reside in dev/evals/specs/ and utilize the @openwork/testkit helpers for browser automation and assertion logic.

Key Testing Architecture Details

Understanding the test script structure in [package.json](https://github.com/different-ai/openwork/blob/dev/package.json) helps troubleshoot failures:

• pnpm -r --if-present: Recursively runs scripts only if they exist in a given package, preventing errors in packages without test definitions
• --filter '!@openwork/app': Explicitly excludes the main Electron application from the default unit test run because it requires heavier E2E infrastructure
• --dir evals: Changes working directory to dev/evals/ before executing evaluation-specific tests

The evaluation specs located at dev/evals/specs/*.test.ts serve dual purposes as both integration tests and benchmarking scenarios for the headless execution engine.

Summary

• Install dependencies first with pnpm install from the repository root
• Run all unit tests using pnpm test, which excludes the desktop app and server for speed
• Target specific packages with pnpm --filter @openwork/package-name test for focused debugging
• Execute E2E tests via pnpm test:e2e or target single specs with file path arguments
• Reference package.json in the repository root to understand the chained test scripts that orchestrate the monorepo validation

Frequently Asked Questions

How do I run tests only for the desktop application?

Use the filter syntax to target the @openwork/app workspace specifically: pnpm --filter @openwork/app test for unit tests, or pnpm --filter @openwork/app test:e2e for the full integration suite.

Why does the default pnpm test skip the Electron app and server?

The root package.json explicitly filters out @openwork/app and openwork-server using --filter '!@openwork/app' --filter '!openwork-server' to keep the standard test run fast. These packages require heavier dependencies and longer startup times, so they are tested separately or via the E2E command.

Can I run a single test file instead of an entire package's suite?

Yes. For E2E tests, append the specific file path after a double dash: pnpm --filter @openwork/app test:e2e -- path/to/specific.test.ts. For package-level unit tests, consult that package's individual test runner configuration (typically Vitest or Jest) for file pattern arguments.

Where are the evaluation test specifications located?

Evaluation specs reside in dev/evals/specs/ and use the .e2e.test.ts extension. These files test the headless execution engine and workspace management logic using the @openwork/testkit utilities, as documented in the sample spec [workspace-storm-auth-coherence.e2e.test.ts](https://github.com/different-ai/openwork/blob/dev/dev/evals/specs/workspace-storm-auth-coherence.e2e.test.ts).

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