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

> Learn how to run tests in OpenSEO using Vitest for unit tests and Playwright for E2E tests. Execute them with pnpm commands after setup.

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

---

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

The `every-app/open-seo` repository maintains a comprehensive test suite to ensure reliability across its SEO tooling features. Understanding how to run tests in the OpenSEO project is essential for contributing code or verifying local changes. This guide covers the exact commands, configuration files, and prerequisites needed to execute both unit and E2E tests.

## Prepare the Local Environment

Before running any tests, you must install dependencies and prepare the local database. OpenSEO uses **pnpm** as its package manager and assumes a fresh SQLite (D1) database for test isolation.

Run the following commands from the repository root:

```bash

# Install all dependencies

pnpm install

# Set up the local SQLite database

pnpm run db:migrate:local

```

As documented in [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md), the database migration step is required because the test suite expects a properly initialized schema.

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

To run all unit tests once:

```bash
pnpm test

```

This command invokes `vitest run` through the npm script defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json). For continuous integration environments where you want a concise "dot" reporter output, use:

```bash
pnpm run test:ci

```

### Watch Mode for Development

While actively developing, keep the test runner watching for file changes to provide immediate feedback:

```bash
pnpm run test:watch

```

### Run Individual Test Files

To execute a specific test file rather than the entire suite, pass the file path directly to Vitest:

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

```

This example references [`src/server/mcp/transport.test.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts), which demonstrates the typical test structure used throughout the repository according to the OpenSEO source code.

## Execute End-to-End Tests with Playwright

The E2E suite validates the application's UI using **Playwright**. These tests require the development server to be running and execute against a real browser instance.

Run the complete E2E suite:

```bash
pnpm test:e2e

```

### Targeted E2E Test Runs

For faster feedback when working on specific features, run only the relevant E2E subsets:

- **Domain overview filters**: `pnpm test:e2e:domain`
- **Keyword research navigation**: `pnpm test:e2e:keywords`

These commands are defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) (lines 40–47) and map to specific Playwright test tags or file patterns.

## Automate Testing in CI Pipelines

For automated checks in continuous integration, combine linting, unit tests, and E2E tests into a single command sequence:

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

```

This pattern runs type checking and linting first (`ci:check`), followed by the concise unit test reporter (`test:ci`), and finally the full Playwright suite.

## Summary

- **Install dependencies** with `pnpm install` and prepare the database with `pnpm run db:migrate:local` before testing.
- **Unit tests** use Vitest configured in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) to match `src/**/*.test.ts`; run with `pnpm test` or `pnpm run test:watch`.
- **E2E tests** use Playwright; execute with `pnpm test:e2e` or target specific areas with `pnpm test:e2e:domain` and `pnpm test:e2e:keywords`.
- **CI pipelines** should use the combined command `pnpm ci:check && pnpm test:ci && pnpm test:e2e` for complete validation.

## Frequently Asked Questions

### What testing frameworks does OpenSEO use?

According to the `every-app/open-seo` source code, the project uses **Vitest** for unit testing and **Playwright** for end-to-end browser testing. 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 tests are driven via npm scripts in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json).

### Do I need to set up a database before running tests?

Yes. You must run `pnpm run db:migrate:local` to initialize a fresh SQLite (D1) database before executing the test suite. The unit and E2E tests assume this database schema is present and will fail if the migration step is skipped.

### How do I run only specific E2E tests instead of the full suite?

OpenSEO provides scoped npm scripts for targeted E2E testing. Use `pnpm test:e2e:domain` to run only the domain‑overview filter tests, or `pnpm test:e2e:keywords` to run only the keyword‑research navigation tests. These commands map to specific Playwright test tags defined in the E2E configuration.

### 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 development. `pnpm run test:ci` executes Vitest with a concise "dot" reporter and is optimized for CI pipelines where minimal output verbosity is preferred. Both commands run the same test files matching `src/**/*.test.ts`.