# How to Run End-to-End Tests for OpenWork: Complete Setup Guide

> Learn how to run end-to-end tests for OpenWork with this complete setup guide. Follow simple commands to execute the full desktop-first test suite and ensure code quality.

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

---

**Run `pnpm test:e2e` after starting the local Den server with `pnpm dev:den` and launching the UI with `pnpm dev` or `pnpm dev:headless-web` to execute the full desktop-first test suite against the OpenWork codebase.**

OpenWork by different-ai is an open-source desktop application that validates user workflows through comprehensive end-to-end (E2E) testing across its Electron interface and local control plane. When you run end-to-end tests for OpenWork, you are verifying the integration between the desktop UI, the **Den** API server, and supporting infrastructure like MySQL and Redis. The test suite lives in `evals/specs/**/*.e2e.test.ts` and leverages the custom `@openwork/testkit` framework built on Vitest.

## Understanding the E2E Architecture

OpenWork’s testing strategy validates the complete user journey from UI interaction through backend persistence. The architecture consists of three coordinated components:

- **Den (Local Server)**: The API gateway and authentication layer running on port **8790**, defined in the `dev:den` script in [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) (lines 71-76). This process automatically spawns Docker containers for MySQL and Redis.
- **User Interface**: Either the full **Electron** desktop app (`apps/@openwork/desktop`) or the **headless web** version ([`scripts/dev-headless-web.ts`](https://github.com/different-ai/openwork/blob/main/scripts/dev-headless-web.ts)) running on port **3005**. The testkit uses Chrome DevTools Protocol (CDP) to drive clicks, navigation, and authentication flows.
- **Test Runner**: Vitest executing the `@openwork/testkit` runner, invoked via the `test:e2e` script in [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) (lines 108-110), which discovers all `*.e2e.test.ts` files under `evals/specs/`.

A typical spec file like [`evals/specs/desktop-server-credential-coherence.test.ts`](https://github.com/different-ai/openwork/blob/main/evals/specs/desktop-server-credential-coherence.test.ts) declaratively sequences steps: launch UI → sign in → create workspace → assert UI state, while automatically tearing down processes after completion.

## Prerequisites

Before executing tests, ensure your environment meets these requirements:

- **Node.js** and **pnpm** installed globally
- **Docker Desktop** running (required for MySQL and Redis containers spawned by `pnpm dev:den`)
- Environment variables configured (the `pnpm dev:den` script automatically sets `DATABASE_URL` and `DEN_DB_ENCRYPTION_KEY`)

## Step-by-Step Test Execution

### Step 1: Install Dependencies

Install all monorepo dependencies from the project root:

```bash
pnpm install

```

### Step 2: Start the Den Server

Launch the local Den control plane, which initializes the database and cache layers:

```bash
pnpm dev:den

```

This command spins up MySQL and Redis via Docker Compose and starts the Den API gateway on **port 8790** and the web UI on **port 3005**.

### Step 3: Launch the User Interface

Choose your test target environment. For realistic desktop behavior:

```bash
pnpm dev

```

For faster execution without Electron overhead, use the headless web launcher (which writes connection details to [`tmp/dev-headless-web.json`](https://github.com/different-ai/openwork/blob/main/tmp/dev-headless-web.json)):

```bash
pnpm dev:headless-web

```

### Step 4: Execute the Test Suite

With Den and the UI running, trigger the Vitest runner:

```bash
pnpm test:e2e

```

The `@openwork/testkit` framework automatically discovers all `evals/specs/**/*.e2e.test.ts` files, orchestrates the browser via CDP, and reports results in the console.

## Running Individual Test Files

To debug a specific scenario without executing the entire suite, pass the file path directly:

```bash
pnpm test:e2e evals/specs/desktop-server-credential-coherence.test.ts

```

This approach loads only the specified spec against the running Den and UI instances, producing targeted output and screenshots in `tmp/` on failure.

## Troubleshooting Common Issues

| Issue | Root Cause | Solution |
|-------|------------|----------|
| **Port conflicts** | Another process occupies the CDP or Vite ports. | Export `OPENWORK_ELECTRON_REMOTE_DEBUG_PORT=0 PORT=0` before running `pnpm dev` to enable dynamic port allocation. |
| **Missing Docker containers** | MySQL or Redis failed to start. | Verify Docker Desktop is running, then execute `pnpm dev:den:mysql` to manually trigger the Docker Compose stack. |
| **Stale profile locks** | Previous dev sessions left lock files. | Delete the lock file referenced in the startup banner (`[openwork] dev profile=…`) or restart with the `--replace` flag. |

## Summary

- **OpenWork E2E tests** verify the full stack from Electron UI through the Den backend using Vitest and `@openwork/testkit`.
- **Test specifications** reside in `evals/specs/**/*.e2e.test.ts` and follow a declarative step-based format.
- **Execution requires** three terminals: one for `pnpm dev:den` (backend), one for `pnpm dev` or `pnpm dev:headless-web` (frontend), and one for `pnpm test:e2e` (runner).
- **Configuration details** for all scripts are defined in [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json), specifically lines 71-76 for the Den server and lines 108-110 for the test command.
- **Debugging artifacts** including screenshots and connection logs are written to the `tmp/` directory.

## Frequently Asked Questions

### What test framework does OpenWork use for E2E testing?

OpenWork uses a custom framework called **@openwork/testkit** built on top of **Vitest**. This framework manages process orchestration, CDP-based browser control, and automatic teardown of the Electron and Den processes between test runs.

### Can I run a single E2E test file instead of the entire suite?

Yes. Append the specific file path to the `pnpm test:e2e` command, such as `pnpm test:e2e evals/specs/desktop-server-credential-coherence.test.ts`. This executes only that spec against the currently running Den server and UI instance.

### Why do OpenWork E2E tests require Docker to be running?

The **Den** control plane (started via `pnpm dev:den`) orchestrates MySQL and Redis services using Docker Compose. These databases persist organization data, authentication states, and workspace configurations that the E2E tests validate through the UI layer.

### How do I resolve port conflicts when running OpenWork E2E tests?

Export the environment variables `OPENWORK_ELECTRON_REMOTE_DEBUG_PORT=0` and `PORT=0` before launching the dev servers. This instructs the Electron and Vite processes to select available random ports instead of defaulting to fixed ports that may be occupied.