# How to Run Tests for Ruflo: A Complete Guide to Vitest Testing

> Learn how to run tests for Ruflo with this guide. Execute the Vitest suite using npm test or explore the interactive browser interface with npm run test:ui. Get started now.

- Repository: [rUv/ruflo](https://github.com/ruvnet/ruflo)
- Tags: how-to-guide
- Published: 2026-03-09

---

**Run `npm test` to execute the full Vitest suite, or use `npm run test:ui` for an interactive browser interface.**

Ruflo, an open-source workflow orchestration framework, ships with a comprehensive test suite powered by **Vitest**. Whether you are contributing new features or verifying local changes, understanding how to run tests for Ruflo ensures code quality and stability.

## Prerequisites for Running Ruflo Tests

Before executing any test commands, ensure your environment meets the repository requirements.

Ruflo requires **Node.js ≥ 20**, as specified in [`package.json`](https://github.com/ruvnet/ruflo/blob/main/package.json) under the `engines` field. Install dependencies using the lockfile to guarantee exact versions:

```bash
npm ci

```

This command reads [`package-lock.json`](https://github.com/ruvnet/ruflo/blob/main/package-lock.json) and installs all necessary packages, including Vitest and its UI components.

## Running the Full Test Suite

The primary method for running tests for Ruflo uses the default npm script defined in [`package.json`](https://github.com/ruvnet/ruflo/blob/main/package.json):

```json
"scripts": {
  "test": "vitest"
}

```

Execute the complete suite with:

```bash
npm test

```

This command discovers and runs all test files located in the `tests/` directory at the repository root and any `__tests__` folders within the `v3/` modules. Vitest automatically runs tests in **multi-threaded mode** using the `pool: 'threads'` configuration specified in [`v3/vitest.config.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/vitest.config.ts).

## Interactive Testing with Vitest UI

For debugging and visual feedback, Ruflo provides a browser-based testing interface. The `test:ui` script launches the Vitest UI:

```bash
npm run test:ui

```

This opens an interactive dashboard where you can filter tests, view real-time results, and inspect individual test failures without scrolling through terminal output.

## Generating Coverage Reports

To measure code coverage while running tests for Ruflo, append the `--coverage` flag. The project uses **V8-based coverage collection** configured in [`v3/vitest.config.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/vitest.config.ts):

```bash
npm test -- --coverage

```

Coverage reports are generated in the `./__tests__/coverage` directory, providing detailed metrics on which lines and functions are exercised by the test suite.

## Running Specific Test Files

When working on a specific feature, you can run individual test files rather than the entire suite. Vitest accepts file paths as arguments:

```bash
npx vitest tests/rvf-integration.test.ts

```

Alternatively, pass the path through the npm script:

```bash
npm test -- tests/rvf-event-log.test.ts

```

This approach significantly reduces feedback time during development.

## Configuration and Test Structure

Understanding the test organization helps navigate the codebase effectively. Key files include:

- **[`package.json`](https://github.com/ruvnet/ruflo/blob/main/package.json)**: Defines npm scripts (`test`, `test:ui`) and Node engine requirements
- **[`v3/vitest.config.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/vitest.config.ts)**: Central configuration specifying the thread pool, coverage provider, and path aliases
- **`tests/`**: Top-level directory containing integration, migration, and capability verification tests
- **`v3/__tests__/`**: Module-level tests for the V3 codebase, including task execution and MCP plugin tests
- **[`v3/__tests__/setup.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/__tests__/setup.ts)**: Global test setup file for mock initialization

The configuration enables **parallel execution** by default, utilizing worker threads for optimal performance on multi-core machines.

## Summary

- Run `npm test` to execute the full Vitest suite across all `tests/` and `v3/__tests__/` directories
- Use `npm run test:ui` for an interactive browser-based testing interface
- Generate coverage reports with `npm test -- --coverage`, outputting to `./__tests__/coverage`
- Execute specific files using `npx vitest <filepath>` or `npm test -- <filepath>`
- Ensure Node.js ≥ 20 is installed and run `npm ci` before testing

## Frequently Asked Questions

### What testing framework does Ruflo use?

Ruflo uses **Vitest** as its primary testing framework. The configuration resides in [`v3/vitest.config.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/vitest.config.ts) and defines V8-based coverage collection, multi-threaded execution via `pool: 'threads'`, and path aliases for the V3 modules.

### How do I run only one test file in Ruflo?

To run a specific test file, pass the file path directly to Vitest: `npx vitest tests/rvf-integration.test.ts`. You can also use the npm script variant: `npm test -- tests/rvf-event-log.test.ts`. This targets only the specified file instead of the entire suite.

### Where are the test files located in the Ruflo repository?

Test files are located in two primary areas: the `tests/` directory at the repository root contains integration, migration, and capability verification tests, while `v3/__tests__/` houses module-level tests for the V3 codebase, including task execution and MCP plugin tests. Global test setup is handled in [`v3/__tests__/setup.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/__tests__/setup.ts).

### What Node.js version is required to run Ruflo tests?

Ruflo requires **Node.js version 20 or higher**, as specified in the `engines` field of [`package.json`](https://github.com/ruvnet/ruflo/blob/main/package.json). Ensure you meet this requirement before installing dependencies with `npm ci` and running the test suite.