@orieken/cucumber-to-docx

Convert Cucumber/Gherkin .feature files into nicely formatted Word .docx documents for manual testing and audits.

Installation

Prerequisites: Node.js 22+ and pnpm.

pnpm add -D @orieken/cucumber-to-docx

CLI Usage

The CLI converts a single .feature file and writes the output into a docx/ folder, preserving the relative folder structure.

# Single file
npx cuke-docx path/to/feature/pokemon.feature
# => docx/path/to/feature/pokemon.docx

# Directory (recursive)
npx cuke-docx features/
# => docx/features/pokemon.docx
# => docx/features/inventory/cart.docx

• Default behavior: give it a file; it outputs with the same base name as .docx under docx/.
• Directory support: Pass a directory path to recursively convert all .feature files while mirroring the folder structure under docx/.

Build and smoke-test the CLI (local project)

Run the CLI against every .feature under the local features/ folder.

# Build the library + CLI, then run the CLI for all features
pnpm cli:smoke:build

# If you already built, just run the smoke test
pnpm cli:smoke

# Clean generated docx/ then smoke test
pnpm cli:smoke:clean

Optional flags:

# Pass a custom config JSON to the CLI for all runs
pnpm cli:smoke --config path/to/config.json

# Increase parallelism (default 1)
pnpm cli:smoke --concurrency 4

Background Support

The tool automatically parses Background sections in your feature files. They are rendered before the scenarios with a configurable header (default "Background").

You can customize the header label in your config:

{
  "document": {
    "labels": {
      "backgroundHeader": "Prerequisites"
    }
  }
}

Step Formatting Options

Remove Gherkin Keywords

Set removeGherkinKeywords: true to remove Given/When/Then/And from the beginning of each step and automatically capitalize the first letter.

Before (default behavior):

Given I am a user with an active account
When I navigate to the "Add Pokemon" section
Then I should see a confirmation message

After (with removeGherkinKeywords: true):

I am a user with an active account
I navigate to the "Add Pokemon" section
I should see a confirmation message

Then Steps as Expected Results

Set thenStepsAsExpectedResults: true to automatically place "Then" steps in the "Expected Result" column of the preceding "When" step, rather than as separate rows.

Default behavior:

• Each step (Given/When/Then) appears as a separate row
• Then steps appear in the "Expected Result" column of their own row

With thenStepsAsExpectedResults: true:

• Then steps are moved to the "Expected Result" column of the previous When step
• Reduces table rows and makes the relationship between actions and expectations clearer

Hide Step Numbers

Set showStepNumbers: false to remove step numbering from the document.

Default behavior (with numbers):

☐ 1. I am a user with an active account
☐ 2. I navigate to the "Add Pokemon" section

With showStepNumbers: false:

☐ I am a user with an active account
☐ I navigate to the "Add Pokemon" section

These options work together:

{
  "document": {
    "removeGherkinKeywords": true,
    "thenStepsAsExpectedResults": true,
    "showStepNumbers": false
  }
}

Configuration (theme + document settings)

You can now customize both the document colors (theme) and document settings (fonts, sizes, labels, table width/borders, checkbox symbol) via JSON.

CLI options:

# Print the full default configuration (theme + document)
npx cuke-docx --print-config

# Use a custom config JSON. Unknown keys are ignored; missing keys fall back to defaults.
# Accepted shapes:
#  1) { "theme": { ... }, "document": { ... } }
#  2) { ...themeKeys } (legacy: theme-only file still supported)
npx cuke-docx features/pokemon.feature --config config.json

# Auto-discovery:
# If you run `cuke-docx` without `--config`, it will look for `cuke-config.json` in the current directory.

Default config (excerpt):

{
  "theme": {
    "headerText": "FFFFFF",
    "bodyText": "000000",
    "stepText": "000000",
    "expectedText": "000000",
    "actualText": "000000",
    "headerBg": "4472C4",
    "dataBgStep": "FFFFFF",
    "dataBgExpected": "F2F2F2",
    "dataBgActual": "FFFFFF",
    "tableBorder": "000000"
  },
  "document": {
    "font": "Arial",
    "sizes": { "title": 32, "description": 22, "scenario": 28, "tableText": 22 },
    "spacing": {
      "titleBefore": 0, "titleAfter": 240,
      "descriptionBefore": 120, "descriptionAfter": 240,
      "scenarioBefore": 360, "scenarioAfter": 120
    },
    "labels": {
      "scenarioPrefix": "Scenario: ",
      "backgroundHeader": "Background",
      "stepHeader": "Step",
      "expectedHeader": "Expected Result",
      "actualHeader": "Actual Result"
    },
    "table": { "widthPct": 100, "borderSize": 4 },
    "checkbox": "☐",
    "removeGherkinKeywords": false,
    "thenStepsAsExpectedResults": false,
    "showStepNumbers": true
  }
}

Programmatic API configuration:

import { convertFeatureFile } from '@orieken/cucumber-to-docx';

await convertFeatureFile('features/a.feature', 'docx/features/a.docx', {
  theme: {
    headerBg: '70AD47',
    dataBgExpected: 'FFF2CC'
  },
  document: {
    font: 'Calibri',
    labels: { scenarioPrefix: 'Test Scenario: ' },
    table: { widthPct: 100, borderSize: 6 },
    checkbox: '[ ]',
    removeGherkinKeywords: true,
    thenStepsAsExpectedResults: true,
    showStepNumbers: false
  }
});

Programmatic API

import { parseFeatureFile, createDocxFromFeature, convertFeatureFile } from '@orieken/cucumber-to-docx';

// Parse a feature string
const parsed = parseFeatureFile(featureText);

// Write a .docx from parsed object
await createDocxFromFeature(parsed, 'docx/example.docx');

// Convert an input file directly
await convertFeatureFile('features/example.feature', 'docx/features/example.docx');

Scripts

pnpm lint        # ESLint (TypeScript, clean-code leaning)
pnpm test        # Vitest (Node environment)
pnpm build       # Vite library build + tsc for CLI
pnpm clean       # Remove build artifacts and generated .docx files
pnpm cli:smoke   # Run the built CLI for all features under ./features (accepts --config, --concurrency)
pnpm cli:smoke:build  # Build first, then smoke
pnpm cli:smoke:clean  # Remove ./docx then smoke

Use in another Node project

You can use this tool either via the CLI or programmatically.

CLI (recommended):

# Install as a dev dependency in your project
pnpm add -D @orieken/cucumber-to-docx

# Convert a single file
npx cuke-docx path/to/feature/example.feature

# Convert all features in a directory recursively
npx cuke-docx features/

Programmatic (library API):

import { convertFeatureFile } from '@orieken/cucumber-to-docx';

await convertFeatureFile('features/a.feature', 'docx/features/a.docx', {
  theme: { headerBg: '70AD47' },
  document: { font: 'Calibri', checkbox: '[ ]' }
});

Development Notes

• Library is built with Vite (ESM).
• CLI is built with TypeScript (tsc) to preserve shebang.
• Output .docx files are placed under docx/ to keep the repo clean.
• Documents and guides moved to docs/ and are not published with the package.
• TODO: Add full CI/CD pipeline (GitHub Actions) once the project is stable.

ESM import specifiers and NodeNext

This project uses TypeScript with module/moduleResolution set to NodeNext. That means all relative ESM imports in source must include a file extension that matches the emitted JavaScript. In TypeScript files, import internal modules using .js in the specifier, for example:

// Correct for NodeNext
import { parseFeatureFile } from './lib/featureParser.js';

If you omit the extension, TypeScript will report TS2835.

CI / CD

This repository includes two GitHub Actions workflows under .github/workflows:

• ci.yml — runs on pushes and pull requests to main. It checks out the code, sets up Node 22 and pnpm, installs dependencies, runs lint, tests, and builds, and uploads build artifacts.
• publish.yml — runs on tag pushes matching v*.*.* and on published releases. It runs the same checks and publishes the package to npm. The publish workflow requires a repository secret NPM_TOKEN with an npm automation token that has publish rights.

To add the NPM_TOKEN secret in GitHub:

1. Create an npm automation token at https://www.npmjs.com/settings//tokens (choose "Automation" and give it publish rights).
2. In your repository on GitHub: Settings → Secrets and variables → Actions → New repository secret. Add NPM_TOKEN with the token value.

How publishing is triggered:

• Push a tag that matches the SemVer pattern, e.g. git tag v1.2.3 && git push origin v1.2.3.
• Or create and publish a GitHub Release that has a tag like v1.2.3.

Notes:

• The workflows are conservative: they use pnpm install --frozen-lockfile to ensure reproducible installs.
• Make sure the version field in package.json matches the tag you push when publishing to npm.

License

MIT © @orieken