# How to Run Tests in the OpenWork Repository: A Complete Guide for Contributors

> Learn to run tests in the OpenWork repository. Discover how to execute unit and end-to-end tests using pnpm workspace filters directly from the monorepo root.

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

---

**Run tests in the OpenWork monorepo using pnpm workspace filters like `pnpm --filter @openwork/app test` for unit tests or `pnpm --filter @openwork/app test:e2e` for end-to-end tests, with all commands orchestrated from the repository root.**

OpenWork is organized as a monorepo managed by **pnpm workspaces**, where the desktop client, web UI, server back-end, and evaluation suite each maintain isolated test suites within their respective packages. Every component ships with its own testing configuration, while the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) provides convenience scripts that chain package-specific commands. To run tests locally, you only need a recent pnpm installation (version 10 or higher) and the repository lockfile ([`pnpm-lock.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-lock.yaml)) ensures reproducible dependencies.

## Prerequisites and Initial Setup

Before executing any test commands, install dependencies from the repository root using the frozen lockfile to guarantee consistent package versions across the workspace.

```bash
pnpm install --frozen-lockfile

```

This command installs all dependencies for every package in the workspace, including the testing frameworks and utilities defined in [`apps/app/package.json`](https://github.com/different-ai/openwork/blob/main/apps/app/package.json) and the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json).

## Running Unit Tests by Component

Unit tests are distributed across packages and executed using pnpm's `--filter` flag to target specific workspace members.

### Web UI Tests (@openwork/app)

The React-based web UI unit tests are defined in [`apps/app/package.json`](https://github.com/different-ai/openwork/blob/main/apps/app/package.json).

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

```

### Server Tests (openwork-server)

The back-end server unit tests run via the same filter pattern.

```bash
pnpm --filter openwork-server test

```

### Desktop Client Tests (@openwork/desktop)

For the Electron-based desktop application, execute the package-specific test suite.

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

```

## Running End-to-End Tests

The end-to-end (e2e) test suite spins up the full application stack to verify health checks, session handling, and file-system engine integration. This command runs a series of Node.js helper scripts located in the UI package's `scripts` folder, including `local-file-path.mjs`, `session-switch.mjs`, `fs-engine.mjs`, and `browser-entry.mjs`.

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

```

As implemented in [`apps/app/package.json`](https://github.com/different-ai/openwork/blob/main/apps/app/package.json), this script orchestrates the browser automation and integration checks that mirror production usage patterns.

## Running the Eval-Runner Tests

OpenWork includes a specification-driven evaluation framework under the `evals` directory. To verify the evaluation harness itself, run the dedicated eval-runner test command defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json).

```bash
pnpm test:eval-runner

```

This command executes the test suite that validates the evaluation runner's ability to process specification files and report results correctly.

## Executing the Full CI Pipeline Locally

To replicate the exact sequence used in continuous integration, chain together all package-specific test commands. This mirrors the steps defined in [`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml) and validates the entire codebase.

```bash
pnpm --filter @openwork/app test && \
pnpm --filter openwork-server test && \
pnpm --filter @openwork/desktop test && \
pnpm test:eval-runner && \
pnpm --filter @openwork/app test:e2e

```

Running this full sequence ensures that changes to any workspace package do not introduce regressions across the UI, server, desktop client, or evaluation framework.

## Key Configuration Files

Understanding these files helps you customize test runs or debug failures:

- **[`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)** (root): Defines the workspace configuration, top-level scripts like `test:eval-runner`, and orchestrates cross-package commands.
- **[`apps/app/package.json`](https://github.com/different-ai/openwork/blob/main/apps/app/package.json)**: Contains granular test definitions including `test`, `test:e2e`, and `test:refactor`, plus references to the e2e helper scripts.
- **[`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml)**: Documents the exact command sequence, caching strategy, and dependency installation steps used in CI.

## Summary

- OpenWork uses **pnpm workspaces** to manage a monorepo structure where tests live within each package.
- Run unit tests for specific components using `pnpm --filter <package-name> test`.
- Execute end-to-end tests with `pnpm --filter @openwork/app test:e2e`, which runs helper scripts like `session-switch.mjs` and `fs-engine.mjs`.
- Validate the evaluation framework using `pnpm test:eval-runner`.
- Replicate the full CI pipeline by chaining all filter commands in the sequence shown in [`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml).

## Frequently Asked Questions

### What testing framework does OpenWork use?

The repository uses **pnpm** as the script runner and task orchestrator, while individual packages leverage their own testing frameworks (likely Vitest or Jest based on modern monorepo patterns) configured within their respective [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) files. The e2e suite relies on Node.js scripts and browser automation tools as defined in [`apps/app/package.json`](https://github.com/different-ai/openwork/blob/main/apps/app/package.json).

### How do I run tests for just one package without running the entire suite?

Use the pnpm `--filter` flag followed by the package name. For example, `pnpm --filter openwork-server test` executes only the server tests, while `pnpm --filter @openwork/desktop test` runs only the desktop client tests. This filtering capability is essential for rapid iteration during development.

### What are the e2e test helper scripts mentioned in the configuration?

According to [`apps/app/package.json`](https://github.com/different-ai/openwork/blob/main/apps/app/package.json), the e2e suite utilizes several Node.js modules located in the `scripts` directory: `local-file-path.mjs` (for file path handling), `session-switch.mjs` (for session management), `fs-engine.mjs` (for file system operations), and `browser-entry.mjs` (for browser initialization). These scripts handle specific integration scenarios during the end-to-end test run.

### Can I run the full CI test suite locally before submitting a pull request?

Yes. By chaining the individual test commands shown in [`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml), you can execute the complete validation pipeline locally. Run the sequence: UI tests, server tests, desktop tests, eval-runner tests, and finally e2e tests. This ensures your changes pass the same gates used in the GitHub Actions workflow.