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

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:

pnpm install

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

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.

Run the full unit test suite once:

pnpm test

This command invokes vitest run through the npm script defined in package.json. For continuous integration pipelines, use the condensed reporter:

pnpm run test:ci

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

pnpm run test:watch

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

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:

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:

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 – Configures Vitest to search for src/**/*.test.ts files and execute in a Node.js environment
• package.json – Defines scripts including test, test:watch, test:ci, and test:e2e
• 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 and 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: 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.

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