# How to Run the Open-SEO Test Suite with Vitest

> Effortlessly run the Open-SEO test suite with Vitest. Execute tests once with pnpm test or use pnpm test:watch for live development updates. Boost your workflow now.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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.

```bash
pnpm install

```

## Running the Test Suite

The [`package.json`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/shared/targetDetection.test.ts) and [`src/shared/selfhost-checks.test.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.test.ts).

```bash
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.

```bash
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.

```bash
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.

```bash

# 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts). This includes specific unit tests like [`src/shared/targetDetection.test.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/targetDetection.test.ts) and [`src/shared/selfhost-checks.test.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.