How to Run Tests in OpenWork: A Complete Guide to pnpm Test Suites

OpenWork uses pnpm as its package manager and defines over a dozen specialized test suites in the root package.json, which you can execute using commands like pnpm test:e2e for end-to-end testing or pnpm test:health for sanity checks after installing dependencies.

OpenWork is a monorepo that relies on pnpm for dependency management and script orchestration. To run tests in OpenWork, you execute predefined npm scripts that cover everything from desktop and web UI validation to session management, filesystem operations, and administrative scalability. All test commands are centrally defined in the repository's package.json file according to the source code.

Available Test Suites in OpenWork

The project defines granular test scripts to isolate different functional areas. You can run these individually or in combination depending on what you need to validate.

End-to-End and Health Check Suites

The primary test suites cover core application functionality:

• pnpm test:e2e – Runs the full end-to-end test suite covering desktop and web UI interactions
• pnpm test:health – Executes basic sanity checks to verify the main app launches correctly
• pnpm test:refactor – Validates that recent refactors haven't broken existing code paths

Session and Permission Testing

OpenWork includes extensive session management validation:

• pnpm test:sessions – Tests session creation, persistence, and cleanup mechanisms
• pnpm test:session-error-recovery – Verifies recovery from crashed or malformed sessions
• pnpm test:session-scope – Ensures data isolation between different sessions
• pnpm test:session-switch – Validates seamless switching between active sessions
• pnpm test:permissions – Checks role-based access control implementations

Infrastructure and Evaluation Tests

Lower-level system components have dedicated test commands:

• pnpm test:fs-engine – Validates the virtual filesystem abstraction layer
• pnpm test:events – Verifies the internal event bus and listener implementations
• pnpm test:todos – Tests TODO-tracking utilities
• pnpm test:eval-runner – Executes the core evaluation harness located in the evals folder via evals/runner/run.mjs
• pnpm test:admin-scale – Tests scalability of admin APIs in the Den backend

How to Execute Test Commands

Running tests in OpenWork requires pnpm and follows a consistent command pattern.

Initial Setup and Installation

Before executing any tests, install the monorepo dependencies:

pnpm install

This command installs all necessary packages across the workspace, including the Vitest testing framework used throughout the project.

Running Individual Test Suites

Execute specific test categories using the pnpm test: prefix:

# Run end-to-end UI tests

pnpm test:e2e

# Run only health checks

pnpm test:health

# Run session management tests

pnpm test:sessions

Running the Full Test Suite

To execute all test scripts sequentially, use the general test command:

pnpm run test

If the root package.json does not define a master test script that chains all suites, you must run the individual commands manually in sequence.

Environment and Dependency Requirements

Some test suites require external services to be running before execution.

Docker Containers for Database Tests

Tests related to the Den backend (particularly pnpm test:admin-scale) expect local MySQL instances. The repository provides Docker configuration to simplify this setup:

• packaging/docker/docker-compose.web-local.yml – Defines the MySQL service configuration for local testing
• dev:den:mysql – Script that automatically spins up the required MySQL container

The scripts/dev-local.mjs file handles the orchestration of these local Den services used by many test suites.

Environment Variables Configuration

Database-dependent tests require specific environment variables:

• DATABASE_URL – Connection string for the MySQL instance
• DEN_DB_ENCRYPTION_KEY – Encryption key for database operations

The default values defined in package.json are safe for local development, but you must ensure these are set when running tests manually outside the provided scripts.

Test Architecture and Key Files

Understanding where tests and configuration reside helps with debugging and extending coverage.

Script Definitions and Configuration

The package.json file in the repository root contains the "scripts" section that defines all available test commands. This is the authoritative source for available test targets and their environment variable defaults.

The evals/runner/run.mjs file serves as the core test runner for the evaluation framework, invoked by pnpm test:eval-runner.

Test Implementation Locations

Actual test files are distributed across the monorepo:

• packages/*/test/*.test.ts – Contains package-specific test implementations using Vitest
• .opencode/* – Includes example test files demonstrating Zod validation testing patterns
• evals/ – Houses the evaluation framework and its associated test scenarios

Summary

• OpenWork uses pnpm exclusively for test execution, with all commands defined in the root package.json
• Individual test suites are run using pnpm test:[suite-name] syntax, covering areas like e2e, sessions, permissions, and filesystem operations
• Docker and MySQL are required for Den-backend tests, with dev:den:mysql automating container setup
• Environment variables like DATABASE_URL must be configured for database-dependent test suites
• Test implementations reside in packages/*/test/*.test.ts and use the Vitest framework

Frequently Asked Questions

What testing framework does OpenWork use?

OpenWork uses Vitest as its primary testing framework. You can see this in action within the .opencode/* example files and throughout the packages/*/test/*.test.ts files, which utilize Vitest's syntax for assertions and test organization.

Do I need Docker to run tests in OpenWork?

You need Docker only for specific test suites that interact with the Den backend, such as pnpm test:admin-scale. These tests require a running MySQL instance. The packaging/docker/docker-compose.web-local.yml file and the dev:den:mysql script handle container orchestration automatically, but pure unit tests do not require Docker.

How do I run only specific test categories?

Use the targeted pnpm scripts defined in package.json. For example, run pnpm test:health for basic sanity checks, pnpm test:sessions for session management, or pnpm test:fs-engine for filesystem validation. Each command isolates a specific functional area of the application.

Where are the actual test files located?

Test implementations are located in packages/*/test/*.test.ts throughout the monorepo, with the evaluation runner housed in evals/runner/run.mjs. Configuration and example tests can also be found in the .opencode/ directory, which demonstrates testing patterns for Zod schemas and other utilities.

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