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

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 under the engines field. Install dependencies using the lockfile to guarantee exact versions:

npm ci

This command reads 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:

"scripts": {
  "test": "vitest"
}

Execute the complete suite with:

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.

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:

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:

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:

npx vitest tests/rvf-integration.test.ts

Alternatively, pass the path through the npm script:

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: Defines npm scripts (test, test:ui) and Node engine requirements
• 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: 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 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.

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. Ensure you meet this requirement before installing dependencies with npm ci and running the test suite.

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