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

# Install all dependencies

pnpm install

# Set up the local SQLite database

pnpm run db:migrate:local

As documented in 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 to search for test files matching the pattern src/**/*.test.ts and executes them in a Node environment.

To run all unit tests once:

pnpm test

This command invokes vitest run through the npm script defined in package.json. For continuous integration environments where you want a concise "dot" reporter output, use:

pnpm run test:ci

Watch Mode for Development

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

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:

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

This example references 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:

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

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 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 to run in a Node environment, while Playwright tests are driven via npm scripts in 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.

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