vite-plugin-gherkin 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Computost Consulting LLC, Joshua Hogsett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# vite-plugin-gherkin
+
+`vite-plugin-gherkin` is a plugin for [Vitest](https://vitest.dev/) that enables you to run your Gherkin feature files as tests. This tool is an attempt to combine the best features of Cucumber/Gherkin with the paradigms and idioms of Vitest as a testing framework.
+
+Check out [Cucumber](https://cucumber.io/) for more info regarding the Gherkin syntax.
+
+## Getting Started
+
+In your [Vitest configuration file](https://vitest.dev/config/), import and register a `vitePluginGherkin` instance. This will allow you to include Gherkin feature files in your test configuration. Also, don't forget to include your step definitions in your test setup:
+
+```ts
+import { vitePluginGherkin } from "vite-plugin-gherkin";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  plugins: [vitePluginGherkin()],
+  test: {
+    include: ["features/**/*.feature"],
+    setupFiles: "features/step-definitions.ts",
+  },
+});
+```
+
+> [!NOTE]
+> Because these will all run using the Vitest runner, both JavaScript and TypeScript are supported.
+
+## Step Definitions
+
+When you write tests with Gherkin, your feature files will have Gherkin steps. `vite-plugin-gherkin` will match these Gherkin steps with step definitions that you will implement to manipulate the system.
+
+```mermaid
+flowchart LR
+  1[Steps in Gherkin] -- matched with --> 2[Step Definitions] -- manipulates --> 3[System]
+```
+
+For an in-depth description on Gherkin and Behavior-Driven Development (BDD), please review [Cucumber's documentation](https://cucumber.io/docs/).
+
+For example, a Gherkin file may have the following steps:
+
+```gherkin
+Scenario: I'm hungry
+  Given I have 10 pickles
+  When I eat 3 pickles
+  Then I have 7 pickles left
+```
+
+In order for `vite-plugin-gherkin` to match Gherkin steps with step definitions, they need to be registered during test setup. This can be done by importing the registry functions `Given`, `When`, and/or `Then` from `vite-plugin-gherkin` and registering step patterns with an implementation.
+
+```ts
+import { Given, When, Then } from "vite-plugin-gherkin";
+
+Given("I have {int} pickles", ([picklesOwned]) => {
+  // ...
+});
+
+When("I eat {int} pickles", ([picklesToEat]) => {
+  // ...
+});
+
+Then("I have {int} pickles left", ([expectedPickles]) => {
+  // ...
+});
+```
+
+`vite-plugin-gherkin` uses [Cucumber Expressions](https://github.com/cucumber/cucumber-expressions) and Regular Expressions for pattern matching. Similar to Vitest's [`test.for`](https://vitest.dev/api/#test-for), template output parameters are passed in order in an array as the 1st argument to the step implementation function.
+
+### Sharing State between Steps
+
+In order to track and share state between step definitions, `vite-plugin-gherkin` uses Vitest's [Test Context](https://vitest.dev/guide/test-context.html). Just like Vitest, you can [extend Test Context](https://vitest.dev/guide/test-context.html#extend-test-context) to setup and teardown fixtures to support your tests.
+
+> [!IMPORTANT]
+> When extending Test Context, your new test function must be exported as `test`.
+
+For example, in JavaScript, you can define your `test-context.js` like so:
+
+```js
+import { test as base } from "vitest";
+
+export const test = base.extend({
+  pickles: ({}, use) => use({ count: 0 }),
+});
+```
+
+Or in TypeScript, you can define your custom fixtures type and re-export `Given`, `When`, and `Then` for some additional type checking:
+
+```ts
+import { test as base } from "vitest";
+import {
+  Given as baseGiven,
+  Then as baseThen,
+  When as baseWhen,
+  type RegisterStep,
+} from "vite-plugin-gherkin";
+
+export interface PickleFixtures {
+  pickles: { count: number };
+}
+
+export const test = base.extend<PickleFixtures>({
+  pickles: ({}, use) => use({ count: 0 }),
+});
+
+export const Given = baseGiven as RegisterStep<PickleFixtures>;
+export const When = baseWhen as RegisterStep<PickleFixtures>;
+export const Then = baseThen as RegisterStep<PickleFixtures>;
+```
+
+When extending Test Context, you must configure the `importTestFrom` option with your test context file:
+
+```ts
+import { vitePluginGherkin } from "vite-plugin-gherkin";
+import { defineConfig } from "vitest/config";
+import { path } from "path";
+
+export default defineConfig({
+  plugins: [
+    vitePluginGherkin({
+      importTestFrom: path.resolve(__dirname, "./features/test-context.ts"),
+    }),
+  ],
+  test: {
+    include: ["features/**/*.feature"],
+    setupFiles: "features/step-definitions.ts",
+  },
+});
+```
+
+Sticking with the [`test.for`](https://vitest.dev/api/#test-for) analogy, step definition implementation functions will accept a 2nd argument which is the [`TestContext`](https://vitest.dev/guide/test-context.html) object.
+
+> [!IMPORTANT]
+> When injecting `TestContext` into a step definition, it must use the object destructuring pattern to communicate to Vitest which dependencies to resolve.
+
+For example:
+
+```ts
+import { Given, When, Then } from "./test-context";
+
+Given("I have {int} pickles", ([picklesOwned], { pickles }) => {
+  pickles.count = picklesOwned;
+});
+
+When("I eat {int} pickles", ([picklesToEat], { pickles }) => {
+  pickles.count -= picklesToEat;
+});
+
+Then("I have {int} pickles left", ([expectedPickles], { pickles }) => {
+  if (pickles.count !== expectedPickles) {
+    throw new Error("I don't have the right amount of pickles!");
+  }
+});
+```

package/dist/data-table.d.ts

@@ -0,0 +1,9 @@
+export declare class DataTable {
+    private readonly rawTable;
+    constructor(rawTable: string[][]);
+    hashes(): Record<string, string>[];
+    raw(): string[][];
+    rows(): string[][];
+    rowsHash(): Record<string, string>;
+    transpose(): DataTable;
+}

package/dist/data-table.js

@@ -0,0 +1,40 @@
+// borrowed directly from the cucumber-js repo with minor modifications
+// https://github.com/cucumber/cucumber-js/blob/release/v11.3.0/src/models/data_table.ts
+export class DataTable {
+    rawTable;
+    constructor(rawTable) {
+        this.rawTable = rawTable;
+    }
+    hashes() {
+        const copy = this.raw();
+        const keys = copy[0];
+        const valuesArray = copy.slice(1);
+        return valuesArray.map((values) => {
+            const rowObject = {};
+            keys.forEach((key, index) => (rowObject[key] = values[index]));
+            return rowObject;
+        });
+    }
+    raw() {
+        return this.rawTable.slice(0);
+    }
+    rows() {
+        const copy = this.raw();
+        copy.shift();
+        return copy;
+    }
+    rowsHash() {
+        const rows = this.raw();
+        const everyRowHasTwoColumns = rows.every((row) => row.length === 2);
+        if (!everyRowHasTwoColumns) {
+            throw new Error("rowsHash can only be called on a data table where all rows have exactly two columns");
+        }
+        const result = {};
+        rows.forEach((x) => (result[x[0]] = x[1]));
+        return result;
+    }
+    transpose() {
+        const transposed = this.rawTable[0].map((x, i) => this.rawTable.map((y) => y[i]));
+        return new DataTable(transposed);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { DataTable } from "./data-table.ts";
+export type { ParameterTypeArgs, RegisterStep } from "./step-registry.ts";
+export { vitePluginGherkin } from "./vite-plugin-gherkin.ts";
+export declare const Given: import("./step-registry.ts").RegisterStep<object>;
+export declare const When: import("./step-registry.ts").RegisterStep<object>;
+export declare const Then: import("./step-registry.ts").RegisterStep<object>;
+declare module "vitest" {
+    interface TaskMeta {
+        tags?: string[];
+    }
+}

package/dist/index.js

@@ -0,0 +1,5 @@
+import { registerStep } from "./step-registry.js";
+export { vitePluginGherkin } from "./vite-plugin-gherkin.js";
+export const Given = registerStep;
+export const When = registerStep;
+export const Then = registerStep;

package/dist/internal.d.ts

@@ -0,0 +1,10 @@
+import type { TestAPI, TestContext } from "vitest";
+export { DataTable } from "./data-table.ts";
+export declare function gherkinContext(test: TestAPI): TestAPI<{
+    task: Readonly<import("vitest").RunnerTestCase<object>>;
+    __gherkin_tags: string[];
+}>;
+export declare function buildTestFunction(testSteps: <T>(step: (text: string, doc?: string) => T) => Generator<T>): (() => void) | {
+    (context: TestContext & unknown): Promise<void>;
+    toString(): string;
+};

package/dist/internal.js

@@ -0,0 +1,102 @@
+import { stripLiteral } from "strip-literal";
+import { getStep } from "./step-registry.js";
+export { DataTable } from "./data-table.js";
+export function gherkinContext(test) {
+    return test.extend({
+        __gherkin_tags: ({}, use) => use([]),
+        task: [
+            ({ __gherkin_tags, task }, use) => {
+                task.meta.tags = __gherkin_tags;
+                return use(task);
+            },
+            { auto: true },
+        ],
+    });
+}
+export function buildTestFunction(testSteps) {
+    const steps = Array.from(testSteps(getStep));
+    if (!allDefined(steps)) {
+        return function reportMissingSteps() {
+            let i = 0;
+            testSteps((text) => {
+                if (!steps[i]) {
+                    throw new Error(`Undefined step: ${text}`);
+                }
+            }).forEach(() => i++);
+        };
+    }
+    const scenarioFunction = async function scenarioFunction(context) {
+        let i = 0;
+        for (const task of testSteps((_, doc) => {
+            const step = steps[i];
+            return step.fn([...step.args.map((arg) => arg.getValue(context)), doc], context);
+        })) {
+            await task;
+            i++;
+        }
+    };
+    scenarioFunction.toString = () => `({${[...new Set(steps.flatMap((step) => getUsedProps(step.fn)))].join(",")}}) => {}`;
+    return scenarioFunction;
+}
+function allDefined(arr) {
+    return arr.every((e) => e != null);
+}
+// borrowed directly from the vitest repo with minor modifications
+// https://github.com/vitest-dev/vitest/blob/v3.2.4/packages/runner/src/fixture.ts#L341
+function getUsedProps(fn) {
+    let fnString = stripLiteral(fn.toString());
+    // match lowered async function and strip it off
+    // example code on esbuild-try https://esbuild.github.io/try/#YgAwLjI0LjAALS1zdXBwb3J0ZWQ6YXN5bmMtYXdhaXQ9ZmFsc2UAZQBlbnRyeS50cwBjb25zdCBvID0gewogIGYxOiBhc3luYyAoKSA9PiB7fSwKICBmMjogYXN5bmMgKGEpID0+IHt9LAogIGYzOiBhc3luYyAoYSwgYikgPT4ge30sCiAgZjQ6IGFzeW5jIGZ1bmN0aW9uKGEpIHt9LAogIGY1OiBhc3luYyBmdW5jdGlvbiBmZihhKSB7fSwKICBhc3luYyBmNihhKSB7fSwKCiAgZzE6IGFzeW5jICgpID0+IHt9LAogIGcyOiBhc3luYyAoeyBhIH0pID0+IHt9LAogIGczOiBhc3luYyAoeyBhIH0sIGIpID0+IHt9LAogIGc0OiBhc3luYyBmdW5jdGlvbiAoeyBhIH0pIHt9LAogIGc1OiBhc3luYyBmdW5jdGlvbiBnZyh7IGEgfSkge30sCiAgYXN5bmMgZzYoeyBhIH0pIHt9LAoKICBoMTogYXN5bmMgKCkgPT4ge30sCiAgLy8gY29tbWVudCBiZXR3ZWVuCiAgaDI6IGFzeW5jIChhKSA9PiB7fSwKfQ
+    //   __async(this, null, function*
+    //   __async(this, arguments, function*
+    //   __async(this, [_0, _1], function*
+    if (/__async\((?:this|null), (?:null|arguments|\[[_0-9, ]*\]), function\*/.test(fnString)) {
+        fnString = fnString.split(/__async\((?:this|null),/)[1];
+    }
+    const match = fnString.match(/[^(]*\(([^)]*)/);
+    if (!match) {
+        return [];
+    }
+    const args = splitByComma(match[1]);
+    if (args.length <= 1) {
+        return [];
+    }
+    const fixtureArg = args[1];
+    if (!(fixtureArg.startsWith("{") && fixtureArg.endsWith("}"))) {
+        throw new Error(`The first argument inside a fixture must use object destructuring pattern, e.g. ({ test } => {}). Instead, received "${fixtureArg}".`);
+    }
+    const _first = fixtureArg.slice(1, -1).replace(/\s/g, "");
+    const props = splitByComma(_first).map((prop) => {
+        return prop.replace(/:.*|=.*/g, "");
+    });
+    const last = props.at(-1);
+    if (last && last.startsWith("...")) {
+        throw new Error(`Rest parameters are not supported in fixtures, received "${last}".`);
+    }
+    return props;
+}
+function splitByComma(s) {
+    const result = [];
+    const stack = [];
+    let start = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === "{" || s[i] === "[") {
+            stack.push(s[i] === "{" ? "}" : "]");
+        }
+        else if (s[i] === stack[stack.length - 1]) {
+            stack.pop();
+        }
+        else if (!stack.length && s[i] === ",") {
+            const token = s.substring(start, i).trim();
+            if (token) {
+                result.push(token);
+            }
+            start = i + 1;
+        }
+    }
+    const lastToken = s.substring(start).trim();
+    if (lastToken) {
+        result.push(lastToken);
+    }
+    return result;
+}

package/dist/step-registry.d.ts

@@ -0,0 +1,25 @@
+import type { TestContext } from "vitest";
+import type { DataTable } from "./data-table.ts";
+type CucumberArgs<Expression extends string> = Expression extends `${string}{${infer Arg}}${infer Post}` ? [
+    Arg extends keyof ParameterTypeArgs ? ParameterTypeArgs[Arg] : unknown,
+    ...CucumberArgs<Post>
+] : [];
+export interface ParameterTypeArgs {
+    "": string;
+    float: number;
+    int: number;
+    string: string;
+    word: string;
+}
+export interface RegisterStep<ExtraContext = unknown> {
+    <Expression extends string>(expression: Expression, step: StepFunction<ExtraContext, CucumberArgs<Expression>>): void;
+    (regExp: RegExp, step: StepFunction<ExtraContext, string[]>): void;
+}
+type StepArgs<Args extends unknown[]> = [...Args, DataTable] | [...Args, string] | Args;
+export type StepFunction<ExtraContext = unknown, Args extends unknown[] = unknown[]> = (args: StepArgs<Args>, context: ExtraContext & TestContext) => Promise<void> | void;
+export declare const registerStep: RegisterStep<object>;
+export declare function getStep(step: string): {
+    args: readonly import("@cucumber/cucumber-expressions").Argument[];
+    fn: StepFunction<unknown, unknown[]>;
+} | null;
+export {};

package/dist/step-registry.js

@@ -0,0 +1,26 @@
+import { CucumberExpression, ParameterTypeRegistry, RegularExpression, } from "@cucumber/cucumber-expressions";
+const stepRegistry = [];
+const parameterTypeRegistry = new ParameterTypeRegistry();
+export const registerStep = (expression, step) => {
+    if (typeof expression === "string") {
+        stepRegistry.push({
+            expression: new CucumberExpression(expression, parameterTypeRegistry),
+            step: step,
+        });
+    }
+    else {
+        stepRegistry.push({
+            expression: new RegularExpression(expression, parameterTypeRegistry),
+            step: step,
+        });
+    }
+};
+export function getStep(step) {
+    for (const { expression, step: fn } of stepRegistry) {
+        const args = expression.match(step);
+        if (args) {
+            return { args, fn };
+        }
+    }
+    return null;
+}

package/dist/vite-plugin-gherkin.d.ts

@@ -0,0 +1,6 @@
+import type { Vite } from "vitest/node";
+declare const defaultConfig: {
+    importTestFrom: string;
+};
+export declare function vitePluginGherkin({ importTestFrom, }?: Partial<typeof defaultConfig>): Vite.Plugin;
+export {};

package/dist/vite-plugin-gherkin.js

@@ -0,0 +1,118 @@
+import { AstBuilder, GherkinClassicTokenMatcher, Parser, } from "@cucumber/gherkin";
+import { IdGenerator, } from "@cucumber/messages";
+import path from "path";
+import { SourceNode } from "source-map-generator";
+const defaultConfig = {
+    importTestFrom: "vitest",
+};
+export function vitePluginGherkin({ importTestFrom = defaultConfig.importTestFrom, } = defaultConfig) {
+    const uuidFn = IdGenerator.uuid();
+    const builder = new AstBuilder(uuidFn);
+    const matcher = new GherkinClassicTokenMatcher();
+    const parser = new Parser(builder, matcher);
+    return {
+        name: "vite-plugin-gherkin",
+        transform(code, id) {
+            if (path.extname(id) === ".feature") {
+                const gherkinDocument = parser.parse(code);
+                if (gherkinDocument.feature) {
+                    const source = new SourceNode()
+                        .add(`import { describe, beforeEach } from "vitest";\n`)
+                        .add(`import { test as base } from ${JSON.stringify(importTestFrom)};\n`)
+                        .add(`import { buildTestFunction, DataTable, gherkinContext } from "vite-plugin-gherkin/internal";\n`)
+                        .add("const test = gherkinContext(base);\n")
+                        .add(buildFeature(gherkinDocument.feature))
+                        .toStringWithSourceMap();
+                    source.map.setSourceContent(id, code);
+                    return {
+                        code: source.code,
+                        map: source.map.toString(),
+                        moduleSideEffects: true,
+                    };
+                }
+            }
+            function buildFeature(feature) {
+                return new SourceNode(feature.location.line, column(feature.location), id, [
+                    "describe(",
+                    JSON.stringify(feature.name),
+                    ", ({ scoped }) => {\n",
+                    ...feature.children.map((child) => {
+                        if (child.rule) {
+                            return buildRule(feature, child.rule);
+                        }
+                        if (child.background) {
+                            return buildBackground(child.background);
+                        }
+                        if (child.scenario) {
+                            return buildScenario(feature, child.scenario);
+                        }
+                        throw new Error("Invalid feature");
+                    }),
+                    "});",
+                ]);
+            }
+            function buildRule(feature, rule) {
+                return new SourceNode(rule.location.line, column(rule.location), id, [
+                    "describe(",
+                    JSON.stringify(rule.name),
+                    ", () => {\n",
+                    ...rule.children.map((ruleChild) => {
+                        if (ruleChild.background) {
+                            return buildBackground(ruleChild.background);
+                        }
+                        if (ruleChild.scenario) {
+                            return buildScenario(feature, ruleChild.scenario);
+                        }
+                        throw new Error("Invalid rule");
+                    }),
+                    "});\n",
+                ]);
+            }
+            function buildBackground(background) {
+                return new SourceNode(background.location.line, column(background.location), id, ["beforeEach(", buildTestFunction(background.steps), ");\n"]);
+            }
+            function buildScenario(feature, scenario) {
+                return new SourceNode(scenario.location.line, column(scenario.location), id, [
+                    "scoped({ __gherkin_tags: [",
+                    new SourceNode()
+                        .add(feature.tags
+                        .concat(scenario.tags)
+                        .map((tag) => new SourceNode(tag.location.line, column(tag.location), id, JSON.stringify(tag.name))))
+                        .join(","),
+                    "]});\n",
+                    "test(",
+                    JSON.stringify(scenario.name),
+                    ", ",
+                    buildTestFunction(scenario.steps),
+                    ");\n",
+                ]);
+            }
+            function buildTestFunction(steps) {
+                return new SourceNode()
+                    .add("buildTestFunction(function*(step) {\n")
+                    .add(steps.map((step) => new SourceNode(step.location.line, column(step.location), id, [
+                    "yield step(",
+                    JSON.stringify(step.text),
+                    ",",
+                    step.dataTable
+                        ? new SourceNode(step.dataTable.location.line, column(step.dataTable.location), id, [
+                            "new DataTable(",
+                            JSON.stringify(rawTable(step.dataTable)),
+                            ")",
+                        ])
+                        : step.docString
+                            ? JSON.stringify(step.docString.content)
+                            : "undefined",
+                    ");\n",
+                ])))
+                    .add("})");
+            }
+        },
+    };
+}
+function column(location) {
+    return location.column !== undefined ? location.column - 1 : null;
+}
+function rawTable(dataTable) {
+    return dataTable.rows.map((row) => row.cells.map((cell) => cell.value));
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "vite-plugin-gherkin",
+  "version": "0.0.0",
+  "description": "",
+  "files": [
+    "./dist/**/*"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./internal": {
+      "type": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    }
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "@eslint/js": "^9.38.0",
+    "@eslint/json": "^0.13.2",
+    "@eslint/markdown": "^7.4.0",
+    "@tsconfig/node-ts": "^23.6.1",
+    "@tsconfig/node22": "^22.0.2",
+    "@types/node": "^24.8.1",
+    "cspell": "^9.2.1",
+    "eslint": "^9.38.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-perfectionist": "^4.15.1",
+    "eslint-plugin-prettier": "^5.5.4",
+    "glob": "^11.0.3",
+    "globals": "^16.4.0",
+    "jiti": "^2.6.1",
+    "lefthook": "^1.13.6",
+    "prettier": "3.6.2",
+    "prettier-plugin-gherkin": "^3.1.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.1",
+    "vite-plugin-gherkin": "link:",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@cucumber/cucumber-expressions": "^18.0.1",
+    "@cucumber/gherkin": "^36.0.0",
+    "@cucumber/messages": "^30.1.0",
+    "source-map-generator": "^2.0.2",
+    "strip-literal": "^3.1.0"
+  },
+  "peerDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "pretest": "pnpm build",
+    "test": "vitest",
+    "build": "tsc --project tsconfig.build.json",
+    "spellcheck": "cspell lint . --config .vscode/cspell.json",
+    "format-gherkin": "prettier --check **/*.feature",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit"
+  }
+}