vitest-bdd

Gherkin test runner for vitest.

The goal is to provide a simple and intuitive way to write tests for your application. Use with vitest and Gherkin extensions for VS-Code.

Tests can run in parallel (no shared state) and are fast and hot reloadable.

Features

• write with Gherkin, execute with vitest !
• async tests
• concurrent testing
• failed tests in steps definitions and Gherkin
• supports number, string and table parameters
• steps are explicitly linked to your context (easy to trace usage)
• supports "Background"
• experimental "Gherkin in markdown"
• ESM and CJS projects support
• Gherkin parsing with @cucumber/gherkin.

Usage

Install

pnpm i --save-dev vitest-bdd

Setup

Create a vitest config file

1// vitest.config.ts
2import { defineConfig } from "vitest/config";
3import { vitestBdd } from "vitest-bdd";
4
5export default defineConfig({
6  plugins: [vitestBdd()],
7  test: {
8    include: ["**/*.feature", "**/*.spec.ts"],
9  },
10});

Describe your features

Define your feature in a file with the .feature extension:

1# src/domain/test/calculator.feature
2Feature: Calculator
3
4  Scenario: Add two numbers
5    Given I have a "basic" calculator
6    When I add 1 and 2
7    Then the result is 3
8
9  Scenario: Advanced calculator
10    Given I have an "rpn" calculator
11    When I enter 1
12    And I enter 2
13    And I divide
14    Then the result is 0.5

Create a steps file with .feature.ts extension (and exact same name as the feature file):

1// src/domain/test/calculator.feature.ts
2import { type Signal } from "tilia";
3import { expect } from "vitest";
4import { Given, type Step } from "vitest-bdd";
5import { makeCalculator } from "../feature/calculator";
6
7// You can reuse steps in multiple contexts
8// Here anything that has a result value.
9function resultAssertions(Then: Step, calculator: { result: Signal<number> }) {
10  // We define an async step, just to look cool 😎.
11  Then("the result is {number}", async (n: number) => {
12    await calculator.proccessBigComputation();
13    expect(calculator.result.value).toBe(n);
14  });
15}
16
17// You can use any variable name instead of When, And, and Then to match the
18// language of the Gherkin messages, such as { Quand, Alors, Et }, etc. We show
19// the code in an async situation (because it's the most difficult to handle).
20Given("I have a {string} calculator", async ({ When, And, Then }, type) => {
21  switch (type) {
22    case "basic": {
23      const calculator = basicCalculator();
24      When("I add {number} and {number}", calculator.add);
25      And("I subtract {number} and {number}", calculator.subtract);
26      And("I multiply {number} by {number}", calculator.multiply);
27      And("I divide {number} by {number}", calculator.divide);
28      resultAssertions(calculator);
29      break;
30    }
31    case "rpn": {
32      const calculator = rpnCalculator();
33      When("I enter {number}", calculator.enter);
34      And("I enter {number}", calculator.enter);
35      And("I divide", calculator.divide);
36      resultAssertions(calculator);
37      break;
38    }
39    default:
40      throw new Error(`Unknown calculator type "${type}"`);
41  }
42});

Reuse steps

You can reuse steps in multiple contexts. For example, a preference manager could implement the interface Form (to access and set values) and you can reuse the form steps:

1// src/domain/test/preference-manager.feature.ts
2import { formSteps } from "@steps/form";
3
4Given("I have a preference manager", ({ Step }) => {
5  const preferenceManager = makePreferenceManager();
6  formSteps(Step, preferenceManager);
7});

Gherkin Markdown

src/domain/test/some.md

1# Feature: Calculator in md
2
3## Background:
4
5- Given I have a "basic" calculator
6- Then the title is "basic"
7
8## Scenario: Add two numbers
9
10- When I add 1 and 2
11- Then the result is 3
12
13## Scenario: Advanced calculator
14
15- When I divide 1 by 2
16- Then the result is 0.5
17
18And this is some more markdown that does nothing.

Define steps in src/domain/test/some.md.ts

Gherkin Table

src/domain/test/tabular.feature

1Feature: Table
2
3  Background:
4    Given I have a table
5      | firstName | lastName | isActive |
6      | Charlie   | Smith    | true     |
7      | Bob       | Johnson  | false    |
8      | Alice     | Williams | true     |
9
10  Scenario: Sort by name
11    When I sort by "lastName"
12    Then the table is
13      | firstName | lastName | isActive |
14      | Bob       | Johnson  | false    |
15      | Charlie   | Smith    | true     |
16      | Alice     | Williams | true     |
17# etc

1// src/domain/test/tabular.feature.ts
2import { Given, Then, When } from "vitest-bdd";
3import { makeTable } from "../feature/table";
4
5Given("I have a table", ({ When, Then }, data) => {
6  // data : string[][]
7  const table = makeTable(data);
8
9  When("I sort by {string}", table.sort);
10  Then("the table is", (data) => {
11    expect([table.headers.map((h) => h.name), ...table.rows.value]).toEqual(
12      data
13    );
14  });
15});

Non-english support

You can write your tests in any language supported by Cucumber (around 40).

1# language: fr
2# /some/feature/calculator.feature
3# language: fr
4Fonctionnalité: Calculatrice
5
6  Scénario: Addition de deux nombres
7    Soit une calculatrice
8    Quand j'ajoute 15 et 10
9    Alors le résultat doit être 25
10
11  Scénario: Addition de nombres négatifs
12    Soit une calculatrice
13    Quand j'ajoute -15 et -10
14    Alors le résultat doit être -25
15
16  Scénario: Soustraction de deux nombres
17    Soit une calculatrice
18    Quand je soustrais 5 à 12
19    Alors le résultat doit être 7

And the steps file:

1// /some/feature/calculator.feature.ts
2import { expect } from "vitest";
3import { Given } from "vitest-bdd";
4import { makeCalculator } from "../feature/calculator";
5
6Soit("un calculator", ({ Quand, Alors }) => {
7  const calculator = makeCalculator();
8  Quand("j'ajoute {number} et {number}", calculator.add);
9  Quand("je soustrais {number} à {number}", calculator.subtract);
10
11  Alors("le résultat doit être {number}", (expected: string) => {
12    expect(calculator.result.value).toBe(expected);
13  });
14});

Don't forget to update some vscode settings (if you use cucumber autocomplete VS Code Extension):

1// .vscode/settings.json
2{
3  "workbench.iconTheme": "diagonal-architecture-light-icon-theme",
4  "cucumberautocomplete.steps": ["src/domain/test/**/*.feature.ts"],
5  "cucumberautocomplete.formatConfOverride": {
6    "Fonctionnalité": 0,
7    "Scénario": 1,
8    "Soit": 2,
9    "Quand": 2,
10    "Alors": 2
11  },
12  "cucumberautocomplete.strictGherkinCompletion": true,
13  "cucumberautocomplete.smartSnippets": true,
14  "cucumberautocomplete.syncfeatures": "src/domain/test/**/*.feature"
15}

And finally, here are some nice extensions for VS Code that can support your BDD journey:

• The Cucumber auto-complete extension adds syntax support and auto-complete for Gherkin.
• The diagonal architecture extension helps structure projects and has icons for .feature and .feature.ts.

1{
2  "recommendations": [
3    "midasum.diagonal-architecture",
4    "alexkrechik.cucumberautocomplete"
5  ]
6}

Changelog

Complete changelog is available here. Changelog is in reverse time order (latest at the top).

• 0.1.0: Canary version

• Add async support

• Add concurrency support

• Fixed negative number parsing

• Added support for scientific number notation

• Create basic plugin