# @cucumber/gherkin-utils

> Various Gherkin utilities

Latest version **12.0.2** (published 2026-08-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cucumber/gherkin-utils
pnpm add @cucumber/gherkin-utils
yarn add @cucumber/gherkin-utils
bun add @cucumber/gherkin-utils
```

Provides the command `gherkin-utils`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 12.0.2 |
| Published | 2026-08-05 |
| First published | 2020-06-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 207.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 20 |
| Author | Cucumber Limited |
| Maintainers | cukebot |
| Keywords | cucumber |

## Links

- npm: https://www.npmjs.com/package/@cucumber/gherkin-utils
- Repository: https://github.com/cucumber/gherkin-utils
- Issues: https://github.com/cucumber/gherkin-utils/issues
- npm.io page: https://npm.io/package/@cucumber/gherkin-utils

## Dependencies (5)

- [commander](https://npm.io/package/commander.md) 15.0.0
- [@cucumber/gherkin](https://npm.io/package/@cucumber/gherkin.md) ^42.0.0
- [@cucumber/messages](https://npm.io/package/@cucumber/messages.md) ^34.0.0
- [@teppeis/multimaps](https://npm.io/package/@teppeis/multimaps.md) 3.0.0
- [source-map-support](https://npm.io/package/source-map-support.md) ^0.5.21

## Recent versions

- 12.0.2 (latest) — 2026-08-05
- 12.0.1 — 2026-06-21
- 12.0.0 — 2026-06-10
- 11.0.0 — 2026-01-25
- 10.0.0 — 2025-09-12
- 9.2.0 — 2025-02-02
- 9.1.0 — 2025-01-22
- 9.0.1 — 2025-01-22
- 9.0.0 — 2024-03-26
- 8.0.6 — 2024-02-23
- 8.0.5 — 2023-06-02
- 8.0.4 — 2023-05-25
- 8.0.3 — 2023-05-11
- 8.0.2 — 2022-11-21
- 8.0.1 — 2022-11-01
- … 15 more at https://npm.io/package/@cucumber/gherkin-utils/versions

## README

<h1 align="center">
  <img src="https://raw.githubusercontent.com/cucumber/cucumber-js/46a5a78107be27e99c6e044c69b6e8f885ce456c/docs/images/logo.svg" alt="Cucumber logo" width="75">
  <br>
  Gherkin Utils
</h1>
<p align="center">
  <b>Utilities for working with Gherkin documents and AST</b>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@cucumber/gherkin-utils">
    <img src="https://img.shields.io/npm/v/@cucumber/gherkin-utils.svg?color=dark-green" alt="npm">
  </a>
  <a href="https://central.sonatype.com/artifact/io.cucumber/gherkin-utils">
    <img src="https://img.shields.io/maven-central/v/io.cucumber/gherkin-utils.svg?label=Maven%20Central&color=dark-green" alt="maven-central">
  </a>
  <a href="https://github.com/cucumber/gherkin-utils/actions/workflows/release-github.yaml">
    <img src="https://github.com/cucumber/gherkin-utils/actions/workflows/release-github.yaml/badge.svg" alt="build">
  </a>
  <a href="https://opencollective.com/cucumber">
    <img src="https://opencollective.com/cucumber/backers/badge.svg" alt="backers">
  </a>
  <a href="https://opencollective.com/cucumber">
    <img src="https://opencollective.com/cucumber/sponsors/badge.svg" alt="sponsors">
  </a>
</p>

## Features

- ✨ Formatting
- 👉 Translation of `.feature` files to `.feature.md`
- 🚶‍♂️ Document walker
- 📁 Document handler

## Install

Gherkin Utils is [available on npm](https://www.npmjs.com/package/@cucumber/gherkin-utils) for JavaScript:

```console
npm install @cucumber/gherkin-utils
```

Gherkin Utils is [available on Maven Central](https://central.sonatype.com/artifact/io.cucumber/gherkin-utils) for Java, by adding the dependency to your `pom.xml`:

```xml
<dependencies>
  <dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>gherkin-utils</artifactId>
    <version>9.0.0</version>
  </dependency>
</dependencies>
```

## Usage

### Command line

To run Gherkin Utils as a formatter, try any of the following:

```bash
# Format `file.feature`
> npx @cucumber/gherkin-utils format features/file.feature
# Format `file.feature` and `other.feature`
> npx @cucumber/gherkin-utils format features/file.feature features/other.feature
# Format feature files directly within `features/`
> npx @cucumber/gherkin-utils format features/*.feature
# Format feature files ending with `_test.feature` in `features`
> npx @cucumber/gherkin-utils format features/*_test.feature
# Format feature files within immediate subdirectories of `features/`
> npx @cucumber/gherkin-utils format features/**/*.feature
```

To convert gherkin feature files to [Markdown with Gherkin](https://github.com/cucumber/gherkin/blob/04da83056751a1d4519d3886448e6fd0a6544fe1/MARKDOWN_WITH_GHERKIN.md) - or the other way around - while formatting, try the following:

```bash
# Format `file.feature` to gherkin markdown `file.feature.md`
npx @cucumber/gherkin-utils format --to-syntax=markdown features/file.feature
# Format `file.feature.md` to gherkin `file.feature`
npx @cucumber/gherkin-utils format --to-syntax=gherkin features/file.feature.md
```

For more details on usage, see the help menu.

```bash
npx @cucumber/gherkin-utils --help
```

### Library

This module can also be used as a library. It provides two main utilities, `pretty` and `gherkinDocumentWalker`.

#### pretty(gherkinDocument: messages.GherkinDocument, syntax: 'gherkin' | 'markdown')

This function takes a GherkinDocument as input and returns a pretty-printed representation in Gherkin or Markdown.

```javascript
import { AstBuilder, GherkinClassicTokenMatcher, Parser } from '@cucumber/gherkin'
import { pretty } from '@cucumber/gherkin-utils'
import { IdGenerator } from '@cucumber/messages'

const uuidFn = IdGenerator.uuid()

const builder = new AstBuilder(uuidFn)
const matcher = new GherkinClassicTokenMatcher()
const parser = new Parser(builder, matcher)

const feature = `Feature:
Scenario:
Given step text`

const gherkinDocument = parser.parse(feature)

const formattedGherkinFeature = pretty(gherkinDocument)
/*
Feature:

  Scenario:
    Given step text

*/
const formattedGherkinMarkdownFeature = pretty(gherkinDocument, 'markdown')
/*
# Feature:

## Scenario:
* Given step text

*/
```

#### GherkinDocumentWalker class

The GherkinDocumentWalker is a class for walking and filtering the AST produced by Gherkin after parsing a feature file.
When running `walkGherkinDocument` on a GherkinDocument, it will produce a deep copy of the object.

It takes two arguments upon creation:

- filters: set of functions used to know if the walked elements are kept in the result. By default, all elements are kept.
- handlers: set of function that can be used to alter the produced elements.

Filtering keeps the meaning of the original GherkinDocument, which means:

- if a `Background` was present, it will always be in the `Feature` (or `Rule`)
- the kept scenarios will have the same steps and examples than the original

By default, all elements are accepted, which means that if you want to do filtering you should reject all other elements. To ease this, we also provide the `rejectAllFilters`.

Here's an example:

```typescript
import { GherkinDocumentWalker, rejectAllFilters } from '@cucumber/gherkin-utils';

// Only keeps scenarios which name include 'magic'
const filter = new GherkinDocumentWalker({
  ...rejectAllFilters,
  ...{ acceptScenario: (scenario) => scenario.name.includes('magic') },
})

// Makes a list with all the scenario names
const allScenarioNames: string[] = []
const scenarioNameFinder = new GherkinDocumentWalker({}, {
  handleScenario: (scenario) => allScenarioNames.push(scenario.name),
})
```

---
_Source: https://npm.io/package/@cucumber/gherkin-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._