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

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

pnpm install

Migrate the Local Database

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

pnpm run db:migrate:local

This step is documented in the project's 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 to match files at src/**/*.test.ts.

Run All Unit Tests Once

pnpm test

This executes vitest run via the npm script defined in package.json (lines 40-47).

Run Tests in CI Mode

For CI pipelines where concise output matters, use:

pnpm run test:ci

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

Run Specific Test Files

Target individual test files directly:

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

The file 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:

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

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:

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 – Configures test environment (Node), file patterns, and coverage settings
• package.json (lines 40-47) – Defines all test scripts and their mapped commands
• 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 and the Playwright setup is managed through package.json scripts.

Can I run Open-SEO tests without pnpm?

No—the Open-SEO repository is configured specifically for pnpm. The 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 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.

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