# How to Run the Tests for OpenSEO: Unit and E2E Test Guide

> Learn how to run tests for OpenSEO with our comprehensive guide. Execute unit and E2E tests using Vitest and Playwright after setting up dependencies and the local database.

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

---

**Run `pnpm test` for unit tests (Vitest) and `pnpm test:e2e` for end-to-end tests (Playwright) after installing dependencies with `pnpm install` and preparing the local database with `pnpm run db:migrate:local`.**

The every-app/open-seo repository uses **Vitest** for unit testing and **Playwright** for end-to-end browser automation. Whether you are validating a new feature or submitting a pull request, executing the complete test suite requires setting up a local SQLite database and running a few targeted pnpm commands.

## Prerequisites: Install Dependencies and Prepare the Database

Before executing any tests, install the project's dependencies using **pnpm**:

```bash
pnpm install

```

The test suite assumes a fresh SQLite (D1) database is available locally. Initialize it by running:

```bash
pnpm run db:migrate:local

```

## Running Unit Tests with Vitest

OpenSEO's unit tests are powered by **Vitest** and located in files matching the pattern `src/**/*.test.ts` as defined in [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts).

Run the full unit test suite 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 pipelines, use the condensed reporter:

```bash
pnpm run test:ci

```

During active development, keep tests running in watch mode to automatically re-execute when files change:

```bash
pnpm run test:watch

```

To run a specific test file, provide the path directly:

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

```

## Running E2E Tests with Playwright

End-to-end tests validate the user interface using **Playwright**. Execute the entire E2E suite with:

```bash
pnpm test:e2e

```

The repository includes targeted scripts for specific functionality:

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

## CI/CD and Automated Testing

For automated pipelines, combine linting checks, unit tests, and E2E tests into a single sequence:

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

```

This command ensures code quality and full test coverage before deployment.

## Key Configuration Files

Understanding the test setup requires referencing these files in the every-app/open-seo repository:

- **[`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts)** – Configures Vitest to search for `src/**/*.test.ts` files and execute in a Node.js environment
- **[`package.json`](https://github.com/every-app/open-seo/blob/main/package.json)** – Defines scripts including `test`, `test:watch`, `test:ci`, and `test:e2e`
- **[`src/server/mcp/transport.test.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.test.ts)** – Example unit test demonstrating the repository's testing patterns

## Summary

- Install dependencies with `pnpm install` and prepare the database with `pnpm run db:migrate:local` before testing
- Execute unit tests using `pnpm test` (single run) or `pnpm run test:watch` (development mode)
- Run specific test files by passing the path directly to the Vitest command
- Execute E2E tests with `pnpm test:e2e` or use targeted scripts like `pnpm test:e2e:domain`
- Use `pnpm ci:check && pnpm test:ci && pnpm test:e2e` for full CI validation

## Frequently Asked Questions

### What testing frameworks does OpenSEO use?

OpenSEO uses **Vitest** for unit testing and **Playwright** for end-to-end testing, as configured in the repository's [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) and [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts) files. The unit tests follow the `src/**/*.test.ts` pattern defined in the Vitest configuration.

### 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 locally before executing the test suite, as the tests expect this database environment to be present and migrated.

### How do I run only specific E2E tests?

Use the targeted npm scripts defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json): `pnpm test:e2e:domain` runs only domain-overview filter tests, while `pnpm test:e2e:keywords` runs only keyword-research navigation tests.

### Can I run a single unit test file instead of the whole suite?

Yes. Pass the specific file path to the Vitest command, for example: `pnpm test src/server/mcp/transport.test.ts`. This allows you to isolate and debug individual test modules during development.