vitest-cucumber-plugin

Plugin for Vitest to allow tests to be written in Cucumber format.

Installation

$ npm install --save-dev vitest-cucumber-plugin

Usage

vite.config.js

Import the plugin then add it to the plugins array. Change test.inclue to look for .feature files.

import { defineConfig } from 'vitest/config'
import vitestCucumberPlugin from 'vitest-cucumber-plugin';

export default defineConfig({
    plugins: [vitestCucumberPlugin()],
    test: {
        include : [ '**/*.feature' ],
        cucumber : {
           tags : "<tags boolean expression>", // Use this to filter the test via boolean tags expression
           log : { 
              level : "<'fatal', 'error', 'warn', 'info', 'debug', 'trace' or 'silent'>",
              file : "<log path>", // Write the logs to a file instead of stdio (the default)
           }
        }
    },
})

Setting the log level to 'info' will cause the plugin to generate logs useful for tracking the state through the steps. You can pipe the logs through pino-pretty to make them more human readable.

Writing tests

Put feature files into the 'features/' directory and step definitions into the 'features/step_definitions/' directory.

See below for the differences between tests written for Cucumber and for this plugin.

Examples

Look in the tests directory for examples on how to use the plugin.

Differences between this plugin and Cucumber

The goal of this plugin is to fully implement Cucumber's Gherkin syntax for feature files, but there are a few differences in how step definitions are written.

Changes to Given/When/Then

The function signatures for Given, When and Then callbacks have been modified in order to make the step definitions more friendly for functional programming. Specifically, the callback functions differ in that they now have three parameters. The first parameter is a state object which was returned by the previous step. The second is an array of parameters values. The third is a data table or a doc string. The callback functions then return a new state object which is passed to the next step definition in the chain.

For example, here is how you'd write step definitions in Cucumber:

const assert = require('assert');
const { Given, When, Then } = require('@cucumber/cucumber');

function isItFriday(today) {
  if (today === "Friday") {
    return "TGIF";
  } else {
    return "Nope";
  }
}

Given('today is {string}', function (givenDay) {
  this.today = givenDay;
});

When('I ask whether it\'s Friday yet', function () {
  this.actualAnswer = isItFriday(this.today);
});

Then('I should be told {string}', function (expectedAnswer, dataTable) {
  assert.strictEqual(this.actualAnswer, expectedAnswer);
});

Here is how you'd write the same step functions in this plugin:

import { Given, When, Then } from 'vitest-cucumber-plugin';
import _ from 'lodash/fp.js';
import { expect } from 'vitest'

Given('today is Sunday', function () {
    return { today : 'Sunday' };
});

Given('today is Friday', function () {
    return { today : 'Friday' };
});

When('I ask whether it\'s Friday yet', function (state) {
    return _.set('answer',(state.today === 'Friday') ? 'TGIF' : 'Nope',state);
});

Then('I should be told {string}', function (state,[ answer ], dataTable) {
    expect(state.answer).toBe(answer);
});

Step definitions must be ECMAScript modules

Currently, all step definition files must be in ECMAScript module format. CommonJS files might work, but this configuration isn't tested.

samuel-ziegler/vitest-cucumber-plugin