# How to Run Tests in OpenSEO: Unit and E2E Testing Guide

> Learn to run tests in OpenSEO. This guide covers Vitest unit tests and Playwright E2E tests using pnpm commands for efficient application testing.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-07-29

---

**OpenSEO uses Vitest for unit tests and Playwright for end‑to‑end (E2E) tests, which you can execute using pnpm commands after installing dependencies and migrating the local SQLite database.**

Running the test suite for the `every-app/open-seo` repository requires two distinct test runners working in concert. Vitest handles the unit test coverage for server‑side logic, while Playwright validates the full user interface flow. Both rely on a properly configured local environment including a fresh D1 SQLite database.

## Prerequisites: Install Dependencies and Prepare the Database

Before executing any tests, you must install Node.js dependencies and initialize the database schema. OpenSEO uses `pnpm` as its package manager and expects a local SQLite (D1) database for test isolation.

Run the following commands from the repository root:

```bash

# Install all dependencies

pnpm install

# Prepare the local SQLite/D1 database

pnpm run db:migrate:local

```

The `db:migrate:local` script is required because the test suite assumes a fresh database state. Skipping this step will cause connection errors in both unit and E2E tests.

## Running Unit Tests with Vitest

OpenSEO configures Vitest in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) to search for test files matching the pattern `src/**/*.test.ts` and executes them in a Node.js environment. The primary entry point for unit testing is the `test` script defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json).

To run the complete unit test suite once:

```bash
pnpm test

```

This command invokes `vitest run`, which executes all discovered tests and exits with a summary. You can verify the exact configuration in [[`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts)](https://github.com/every-app/open-seo/blob/main/vitest.config.ts), where the `include` array specifies the glob pattern for test discovery.

### Watch Mode for Development

During active development, run Vitest in watch mode to automatically re‑execute relevant tests when source files change:

```bash
pnpm run test:watch

```

This keeps the test runner active in your terminal, providing immediate feedback as you modify code in `src/`.

### CI-Friendly Test Execution

For continuous integration pipelines where concise output is preferred, use the CI‑optimized script:

```bash
pnpm run test:ci

```

This variation runs Vitest with a "dot" reporter, minimizing log noise while still reporting failures and final coverage statistics.

## Running E2E Tests with Playwright

The E2E suite validates the domain overview and keyword research UI flows. These tests are defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) under the `test:e2e` namespace and require a running local server (implied by the Playwright configuration).

Execute the full Playwright suite:

```bash
pnpm test:e2e

```

OpenSEO also provides granular scripts to run specific E2E subsets:

- **`pnpm test:e2e:domain`** – Runs only the domain‑overview filter tests
- **`pnpm test:e2e:keywords`** – Runs only the keyword‑research navigation tests

These targeted scripts are useful when debugging specific features without incurring the overhead of the entire E2E suite.

## Running Specific Test Files

You can bypass the glob pattern and run individual unit test files directly by passing the file path to Vitest:

```bash
pnpm test src/server/mcp/transport.test.ts

```

This approach is demonstrated in the example unit test located at [[`src/server/mcp/transport.test.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts)](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts), which shows the standard structure for server‑side tests in the repository.

## Complete CI Pipeline Example

A typical continuous integration job combines linting, unit testing, and E2E validation in a single command chain:

```bash
pnpm ci:check && pnpm test:ci && pnpm test:e2e

```

This sequence ensures that static analysis passes before executing the expensive test suites, failing fast on code quality issues.

## Summary

- **Install and migrate first**: Always run `pnpm install` and `pnpm run db:migrate:local` before testing.
- **Unit tests**: Use `pnpm test` for single runs, `pnpm run test:watch` for development, and `pnpm run test:ci` for CI pipelines.
- **E2E tests**: Use `pnpm test:e2e` for the full suite, or target specific features with `pnpm test:e2e:domain` and `pnpm test:e2e:keywords`.
- **File paths**: Vitest looks for `src/**/*.test.ts` as configured in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts), matching patterns like [`src/server/mcp/transport.test.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts).

## Frequently Asked Questions

### What testing frameworks does OpenSEO use?

OpenSEO uses **Vitest** for unit testing server‑side code and **Playwright** for end‑to‑end browser automation. Vitest is configured in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) to run in a Node environment, while Playwright handles UI validation.

### Why do I need to run database migrations before testing?

The test suite assumes a fresh SQLite (D1) database schema. Running `pnpm run db:migrate:local` ensures that tables and indexes exist before tests attempt to write or read data, preventing connection and schema errors during execution.

### How do I run only one specific test file?

Pass the relative file path directly to the test command: `pnpm test src/server/mcp/transport.test.ts`. This leverages Vitest's file filtering to execute only the specified test file instead of the entire `src/**/*.test.ts` glob.

### What is the difference between `pnpm test` and `pnpm run test:ci`?

`pnpm test` runs Vitest with the default reporter, showing detailed output suitable for local debugging. `pnpm run test:ci` uses a "dot" reporter that minimizes log noise, making it ideal for CI environments where only pass/fail status and coverage summaries are needed.