# How to Run Open-SEO Tests: A Complete Guide to Vitest and Playwright

> Learn to run Open-SEO tests with Vitest and Playwright. Execute unit tests using pnpm test and e2e tests with pnpm test:e2e. A complete guide for developers.

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

---

**Run Open-SEO tests using `pnpm test` for unit tests with Vitest and `pnpm test:e2e` for end-to-end tests with Playwright, after installing dependencies and migrating the local database.**

The Open-SEO repository from every-app uses a dual testing architecture: **Vitest** for fast unit tests and **Playwright** for comprehensive E2E coverage. This guide shows you exactly how to run the Open-SEO test suite locally or in CI pipelines, with commands verified against the project's [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) and configuration files.

## Prerequisites: Install Dependencies and Database

Before running any Open-SEO tests, you need to prepare your environment.

### Install Node Dependencies

The project uses **pnpm** as its package manager. Run this first:

```bash
pnpm install

```

### Migrate the Local Database

Open-SEO tests assume a fresh SQLite (D1) database. The migration command creates this:

```bash
pnpm run db:migrate:local

```

This step is documented in the project's [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md) and is required for both unit and E2E tests to pass.

## Running Open-SEO Unit Tests with Vitest

Unit tests in Open-SEO are powered by **Vitest**, configured in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) to match files at `src/**/*.test.ts`.

### Run All Unit Tests Once

```bash
pnpm test

```

This executes `vitest run` via the npm script defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) (lines 40-47).

### Run Tests in CI Mode

For CI pipelines where concise output matters, use:

```bash
pnpm run test:ci

```

This runs Vitest with a "dot" reporter for minimal verbosity.

### Run Specific Test Files

Target individual test files directly:

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

```

The file [`src/server/mcp/transport.test.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts) demonstrates the typical test structure used throughout the repository.

### Watch Mode for Development

Keep tests running during active development:

```bash
pnpm run test:watch

```

Vitest will automatically re-run affected tests when you save file changes.

## Running Open-SEO E2E Tests with Playwright

End-to-end tests verify the full application stack through browser automation.

### Run Full E2E Suite

```bash
pnpm test:e2e

```

### Run Targeted E2E Test Subsets

Open-SEO provides granular E2E scripts for faster feedback:

| Command | Tests Covered |
|---------|-------------|
| `pnpm test:e2e:domain` | Domain-overview filter functionality |
| `pnpm test:e2e:keywords` | Keyword-research navigation flows |

## Complete CI Pipeline Example

Combine all quality checks in one sequence as implemented in the Open-SEO repository:

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

```

This runs linting/type-checking, unit tests, and E2E tests sequentially—matching the pattern used in production CI jobs.

## Key Configuration Files

Understanding these files helps you customize or debug the Open-SEO test setup:

- **[`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts)** – Configures test environment (Node), file patterns, and coverage settings
- **[`package.json`](https://github.com/every-app/open-seo/blob/main/package.json)** (lines 40-47) – Defines all test scripts and their mapped commands
- **[`src/server/mcp/transport.test.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts)** – Reference implementation showing standard test patterns

## Summary

- Open-SEO uses **Vitest** for unit tests (`pnpm test`) and **Playwright** for E2E tests (`pnpm test:e2e`)
- Always run `pnpm run db:migrate:local` before testing to prepare the SQLite database
- Use `pnpm run test:watch` during development for immediate feedback
- Use `pnpm run test:ci` for pipeline-friendly output
- Target specific E2E areas with `:domain` and `:keywords` script variants

## Frequently Asked Questions

### What testing frameworks does Open-SEO use?

Open-SEO uses **Vitest** for unit testing and **Playwright** for end-to-end browser testing. This combination provides fast feedback during development and confident coverage of user workflows. The configuration lives in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) and the Playwright setup is managed through [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) scripts.

### Can I run Open-SEO tests without pnpm?

No—the Open-SEO repository is configured specifically for pnpm. The [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) scripts and lockfile assume pnpm's dependency resolution and workspace handling. While you could theoretically adapt the commands, the documented and supported workflow requires `pnpm install` and subsequent `pnpm` commands.

### How do I run only a specific test file in Open-SEO?

Pass the file path directly to the test command: `pnpm test src/server/mcp/transport.test.ts`. This works because the Vitest configuration in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) accepts file arguments, letting you isolate tests for faster iteration when debugging specific functionality.

### What database do Open-SEO tests require?

Open-SEO tests require a **SQLite (D1-compatible) database** migrated via `pnpm run db:migrate:local`. Both unit and E2E tests assume this database exists and is seeded with the correct schema. Skipping this step will cause database-dependent tests to fail with connection or migration errors.