How to Run the Open-SEO Test Suite with Vitest

Run pnpm test to execute the full Vitest suite once, or pnpm test:watch for continuous testing during development.

The Open-SEO repository uses Vitest as its unit-test runner to validate SEO utilities and target detection logic. Located at every-app/open-seo, the project configures Vitest via vitest.config.ts to execute tests matching src/**/*.test.ts in a Node environment.

Install Dependencies

Before running tests, install the required packages using the project's pnpm lockfile.

pnpm install

Running the Test Suite

The package.json defines several npm scripts that wrap Vitest commands for common workflows.

Execute All Tests Once

To run the complete test suite a single time and exit—mimicking the CI environment—use the test script. This invokes vitest run against all files matching the src/**/*.test.ts pattern, such as src/shared/targetDetection.test.ts and src/shared/selfhost-checks.test.ts.

pnpm test

Watch Mode for Development

During active development, keep tests running in watch mode to automatically re-execute when files change. This provides immediate feedback on code modifications.

pnpm test:watch

CI Execution

For continuous integration pipelines, the repository provides a dedicated script that runs Vitest with a compact dot reporter to minimize log verbosity.

pnpm test:ci

This executes vitest run --reporter=dot as defined in the project configuration.

Direct Vitest Commands

You can bypass the npm wrappers and invoke Vitest directly using npx. This approach allows additional flags for custom reporting or coverage analysis.

# Run once (equivalent to pnpm test)

npx vitest run

# Run with coverage report

npx vitest run --coverage

# Interactive watch mode (equivalent to pnpm test:watch)

npx vitest

Configuration Details

The testing behavior is governed by vitest.config.ts in the repository root. This configuration specifies:

• Environment: Node.js runtime for server-side SEO logic validation
• Test file pattern: src/**/*.test.ts glob matching all TypeScript test files under src/
• Mock handling: Configured for testing utilities like target detection and self-hosting checks

Example test files located at src/shared/targetDetection.test.ts demonstrate the unit test structure used throughout the codebase, validating functions such as detectTarget and self-hosting validation utilities.

Summary

• Primary command: Use pnpm test to execute the full Open-SEO test suite with Vitest in a single pass.
• Development workflow: Run pnpm test:watch for automatic test re-execution on file changes.
• CI optimization: Use pnpm test:ci for compact dot-reporter output suitable for pipeline logs.
• Configuration source: All settings reside in vitest.config.ts, ensuring consistency between local runs and CI environments.
• Direct access: Invoke npx vitest run directly for custom flags like --coverage without npm script wrappers.

Frequently Asked Questions

What test files does Vitest discover in Open-SEO?

Vitest scans for files matching the src/**/*.test.ts glob pattern as configured in vitest.config.ts. This includes specific unit tests like src/shared/targetDetection.test.ts and src/shared/selfhost-checks.test.ts that validate SEO detection logic and self-hosting validation rules.

How do I run a single test file instead of the whole suite?

Invoke Vitest directly with the specific file path: npx vitest run src/shared/targetDetection.test.ts. This executes only the specified test file while still applying the configuration from vitest.config.ts.

Does the Open-SEO test suite generate coverage reports?

Yes, run npx vitest run --coverage to generate a coverage report. The repository includes Vitest as a dev dependency, which supports coverage analysis when the appropriate flag is passed during execution.

Which package manager does Open-SEO use for testing?

The repository uses pnpm exclusively, evidenced by the pnpm lockfile. All test scripts (pnpm test, pnpm test:watch, pnpm test:ci) assume dependencies were installed via pnpm install rather than npm or yarn.

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