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

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:

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

To run the complete unit test suite once:

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), 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:

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:

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 under the test:e2e namespace and require a running local server (implied by the Playwright configuration).

Execute the full Playwright suite:

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:

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), 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:

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, matching patterns like 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 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.

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