@deepracticex/vitest-cucumber-plugin

Internal implementation package - Users should install @deepracticex/vitest-cucumber instead.

For Users

This package contains the build-time transformation logic for Cucumber feature files. You don't need to install it directly.

Install the main package instead:

pnpm add -D @deepracticex/vitest-cucumber

See the main documentation for usage guide.

For Contributors & Advanced Users

This package is the compile-time plugin that transforms .feature files into Vitest test code.

Architecture Role

User Code (.feature files)
    ↓
vitest-cucumber-plugin (this package)
    • Parses Gherkin with @cucumber/gherkin
    • Generates Vitest test code
    • Handles step discovery
    ↓
Generated Test Code
    ↓
vitest-cucumber (runtime)
    • Executes steps
    • Manages hooks
    • Provides DataTable API

Key Features

• Build-time transformation - Zero runtime overhead
• Official Gherkin parser - Uses @cucumber/gherkin
• Auto-discovery - Finds step definitions automatically
• Configurable runtime - Support for wrapper packages via runtimeModule option

Plugin Configuration

import { vitestCucumber } from '@deepracticex/vitest-cucumber-plugin';

vitestCucumber({
  // Feature file patterns
  features: ['features/**/*.feature'],

  // Step definitions directory
  steps: 'tests/steps',

  // Support files (hooks, world, custom types) - OPTIONAL
  // Auto-discovered if not specified
  support: 'tests/support', // or ['tests/support', 'src/fixtures']

  // Runtime module for imports
  runtimeModule: '@deepracticex/vitest-cucumber', // default

  // Verbose logging
  verbose: false,
});

Support Directory Auto-Discovery

If support is not specified, the plugin automatically searches for support files in:

1. Smart detection - Same parent as steps directory:

   • steps='tests/bdd/steps' → checks tests/bdd/support
   • steps='tests/e2e/steps' → checks tests/e2e/support
   • steps='src/test/steps' → checks src/test/support

2. Common fallback locations:

   • tests/e2e/support/**/*.ts
   • tests/support/**/*.ts
   • tests/bdd/support/**/*.ts
   • ${steps}/support/**/*.ts

Support files are always loaded BEFORE step definitions to ensure hooks and world setup are available.

Examples

// Example 1: Auto-discovery (recommended)
vitestCucumber({
  steps: 'tests/bdd/steps',
  // Automatically finds: tests/bdd/support
});

// Example 2: Explicit single directory
vitestCucumber({
  steps: 'tests/steps',
  support: 'tests/support',
});

// Example 3: Multiple support directories
vitestCucumber({
  steps: 'tests/steps',
  support: ['tests/support', 'src/test/fixtures'],
});

Implementation Details

Transformation Pipeline:

1. Parse .feature file with @cucumber/gherkin
2. Extract scenarios, backgrounds, examples
3. Generate Vitest test code with proper imports
4. Auto-discover and import step definitions

Code Generation:

• Each Feature → describe() block
• Each Scenario → it() test
• Background steps → Run before each scenario
• Scenario Outline → Multiple it() tests with data

Custom Runtime Module

For wrapper packages, use runtimeModule to redirect imports:

vitestCucumber({
  runtimeModule: '@your-org/testing-utils',
});

Generated code will import from your package instead:

import { StepExecutor } from '@your-org/testing-utils/runtime';

Your package re-exports from @deepracticex/vitest-cucumber:

export * from '@deepracticex/vitest-cucumber/runtime';

Contributing

See the main repository for contribution guidelines.

License

MIT