Vitest Plugin

vitest-cucumber is a framework built on top of Vitest. It wraps Vitest’s lifecycle methods (describe, test, beforeAll, etc.) behind Gherkin keywords, so your test structure mirrors the feature file.

Vitest	vitest-cucumber	When to use
describe	describeFeature / Scenario / Rule	Grouping tests — driven by your .feature file
test	Given / When / Then / And / But	Individual assertions — each step is a test
beforeAll	BeforeAllScenarios	One-time setup before all scenarii
beforeEach	BeforeEachScenario / Background	Per-scenario setup
afterEach	AfterEachScenario	Per-scenario teardown
afterAll	AfterAllScenarios	One-time teardown after all scenarii

State management

Because vitest-cucumber controls the test lifecycle, avoid mixing Vitest’s beforeAll/beforeEach with vitest-cucumber hooks in the same file. Use Background for shared Given steps, Hooks for setup/teardown, Predefine steps for reusable steps across scenarii, and Structure context to share state between steps within a scenario.

Vitest plugin

Since 4.1.1 vitest-cucumber provides a Vitest plugin to automatically create and update .spec.ts files when .feature files change.

This plugin is optional — it does not change how vitest-cucumber runs tests.

Note: currently this plugin doesn’t work with vitest browser mode.

Use plugin

Add plugin in your vitest.config.js:

import { defineConfig } from "vitest/config"
import { VitestCucumberPlugin } from "@amiceli/vitest-cucumber"

export default defineConfig({
    // ...
    plugins: [
        VitestCucumberPlugin({
            specFilesDir: 'src/__tests__/',
            featureFilesDir : 'src/features/',
        })
    ],
    // ...
})

Now when you run vitest, vitest-cucumber will watch your .feature file in src/features.

By example, if your create src/features/user-auth.feature, vitest-cucumber will create src/__tests__/user-auth.spec.ts file like npx @amiceli/vitest-cucumber does.

Update spec file

When your .feature file change, vitest-cucumber updates spec file.

By example your .feature file

Feature: User
    Scenario: User login page
        Given User on login page

You spec file:

describeFeature(feature, ({ Scenario }) => {
    Scenario(`User login page`, ({ Given }) => {
        Given(`User on login page`, () => {})
    })
})

If you add a new step like When I click on "login" button, vitest-cucumber add new step in your spec file :

describeFeature(feature, ({ Scenario }) => {
    Scenario(`User login page`, ({ Given, When }) => {
        Given(`User on login page`, () => {})
        When(`I click on "login" button`, () => {})
    })
})

Features

vitest-cucumber-plugin what your changes in .feature file:

• add / remove Scenario, ScenarioOutline, Background from Rule and Feature
• add / remove step(s) from Scenario, ScenarioOutline and Background
• update arrow functions arguments, by example :
  • removes And from { Given, When, And} if you remove last Scenario And step
  • add Backgorund in { Scenario } if you add a Background in your Rule / Feature

vitest-cucumber-plugin will match steo even if you use step expression.

By example When('I click on {string} button', () => {}) match with When I click on "login" button.

To check and update code vitest-cucumber-plugin uses ts-moprh ❤️.

Configuration

vitest-cucumber-plugin provides some options:

• formatCommand (optional): will run a command to format spec file after update
  • by example : npx biome check --write
  • plugin will pass spec file pass to your command
• onDeleteAction (optional) : define how to handle remove code from .feature file
  • delete (default value): plugin will remove code in your spec file
  • comment plugin will comment code in your spec file

Example:

// When(`I click on "login" button`, () => {
//     console.debug('login')
// })