Cucumber / Gherkin plugin for Vitest - with official @cucumber/cucumber runtime

[matus-sabo]

Hi all,

I've built a Vitest plugin that lets you run Cucumber/Gherkin .feature files as first-class Vitest tests, using the official @cucumber/cucumber runtime under the hood.

GitHub: https://github.com/lotun-io/vitest-cucumber
npm: https://www.npmjs.com/package/@lotun/vitest-cucumber

What makes it different

Unlike other cucumber-vitest integrations, this one doesn't reimplement the Cucumber runtime — it delegates execution entirely to @cucumber/cucumber's API. This means everything Cucumber supports works out of the box: Scenario Outlines, Backgrounds, Rules, Tags, Hooks, custom Worlds, CUCUMBER_OPTIONS, etc.

Key features

• .feature files appear as regular test files in Vitest's output with clickable error locations
• Full parallel execution via Vitest's worker-based parallelism (CUCUMBER_WORKER_ID is synced with VITEST_WORKER_ID)
• Coverage, watch mode, and all Vitest tooling work as expected
• Step definitions written with standard @cucumber/cucumber imports — no custom API to learn
• Tag filtering via CUCUMBER_OPTIONS="--tags @smoke" npx vitest run
• Line number targeting — run a specific scenario or outline by appending :line to the feature file path (e.g. npx vitest run features/simple.feature:5)

Example

vitest.config.ts

import { defineConfig } from "vitest/config";
import { cucumber } from "@lotun/vitest-cucumber";

export default defineConfig({
  plugins: [
    cucumber({
      import: ["features/support/**/*.ts", "features/step_definitions/**/*.ts"],
    }),
  ],
  test: {
    environment: "node",
    include: ["features/**/*.feature"],
  },
});

features/arithmetic.feature

Feature: Arithmetic

  Scenario: Double a value
    Given a value of 3
    When I double it
    Then the value should be 6

features/support/world.ts

import { setWorldConstructor } from "@cucumber/cucumber";

export class ArithmeticWorld {
  value = 0;
}

setWorldConstructor(ArithmeticWorld);

features/step_definitions/arithmetic.ts

import { Given, When, Then } from "@cucumber/cucumber";
import type { ArithmeticWorld } from "../support/world.ts";

Given("a value of {int}", function (this: ArithmeticWorld, n: number) {
  this.value = n;
});

When("I double it", function (this: ArithmeticWorld) {
  this.value *= 2;
});

Then("the value should be {int}", function (this: ArithmeticWorld, expected: number) {
  if (this.value !== expected) {
    throw new Error(`Expected ${expected} but got ${this.value}`);
  }
});

Would love feedback from the community!