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

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 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) 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.

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 and the root 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.

pnpm --filter @openwork/app test

Server Tests (openwork-server)

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

pnpm --filter openwork-server test

Desktop Client Tests (@openwork/desktop)

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

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.

pnpm --filter @openwork/app test:e2e

As implemented in 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.

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 and validates the entire codebase.

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 (root): Defines the workspace configuration, top-level scripts like test:eval-runner, and orchestrates cross-package commands.
• 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: 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.

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 files. The e2e suite relies on Node.js scripts and browser automation tools as defined in 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, 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, 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.

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