@l8d/gherkin-lite

Gherkin-style BDD testing DSL for vitest. Write feature tests with Given/When/Then step definitions.

Installation

npm install @l8d/gherkin-lite

Peer Dependencies

This package requires vitest (>=1.0.0) and debug (^4.0.0) as peer dependencies. Install them if not already present:

npm install -D vitest debug

Usage

Step 1: Define Step Handlers

Create step definition files using Given, When, and Then:

// steps/when/startGame.ts
import { When } from '@l8d/gherkin-lite/steps'

When('the user starts a new game', async ({ scenario }) => {
  // Your step implementation
})

Steps can accept string or regex patterns:

import { When } from '@l8d/gherkin-lite/steps'

When(/player (\w+) moves to cell \((\d+), (\d+)\)/, async ({ params }) => {
  const [, player, row, col] = params
  // Implementation with captured groups
})

Step 2: Write Feature Tests

Import your step handlers as side effects, then define features with scenarios:

import { Feature } from '@l8d/gherkin-lite'
// Step imports register handlers
import './steps/when/startGame'
import './steps/then/gameShouldShowStatus'

Feature('Tic Tac Toe Game', ({ Scenario }) => {
  Scenario('Starting a new game', [
    'Given the app is rendered',
    'When the user starts a new game',
    'Then the game should show status "Next player: X"',
  ])
})

Custom Fixtures

Pass custom data to all scenarios in a feature:

import { Feature } from '@l8d/gherkin-lite'

Feature<{ routes: React.ReactNode }>(
  'My Feature',
  { routes: myRoutes },
  ({ Scenario }) => {
    Scenario('Test scenario', [
      'Given something',
      'When something happens',
      'Then verify the result',
    ])
  },
)

Step handlers receive custom fixtures:

import { Given } from '@l8d/gherkin-lite/steps'

Given('the app is rendered', async ({ routes }) => {
  // routes is available from custom fixtures
})

API

Feature<TCustom>

Feature<{ routes: React.ReactNode }>(
  name: string,
  options?: { only?: boolean; skip?: boolean } & Partial<TCustom>,
  block: ({ Scenario }) => void,
)

Defines a feature with named scenarios. Registers tests with vitest.

Scenario

Scenario(
  name: string,
  steps: string[],
)

Defines a scenario within a feature. Steps must start with Given, When, Then, or And.

Given, When, Then

Given(text: string | RegExp, handler: HandlerFn<TCustom>) => void
When(text: string | RegExp, handler: HandlerFn<TCustom>) => void
Then(text: string | RegExp, handler: HandlerFn<TCustom>) => void

Register step handlers. Handlers receive fixtures with scenario.id, params (regex captures), and custom fixture data.

Export Paths

• @l8d/gherkin-lite — Feature
• @l8d/gherkin-lite/steps — Given, When, Then
• @l8d/gherkin-lite/types — TypeScript type definitions