@cucumber/gherkin

What is @cucumber/gherkin?

@cucumber/gherkin is an npm package that provides tools for parsing Gherkin language, which is used for writing structured tests in a human-readable format. It is part of the Cucumber suite of tools for Behavior-Driven Development (BDD). The package allows you to parse Gherkin documents, extract feature files, and convert them into a format that can be used for automated testing.

What are @cucumber/gherkin's main functionalities?

Parsing Gherkin Documents

This feature allows you to parse Gherkin documents from a stream. The code sample demonstrates how to create a readable stream from a Gherkin source string and parse it using GherkinStreams. The parsed data is then logged to the console.

const { GherkinStreams } = require('@cucumber/gherkin');
const { Readable } = require('stream');

const gherkinSource = `
Feature: Example feature
  Scenario: Example scenario
    Given a step
    When another step
    Then a final step
`;

const stream = Readable.from([gherkinSource]);
const parser = GherkinStreams.fromStream(stream);

parser.on('data', (envelope) => {
  console.log(JSON.stringify(envelope, null, 2));
});

Extracting Feature Files

This feature allows you to extract and parse feature files from the file system. The code sample demonstrates how to create a readable stream from a feature file and parse it using GherkinStreams. The parsed data is then logged to the console.

const { GherkinStreams } = require('@cucumber/gherkin');
const fs = require('fs');

const filePath = 'path/to/your/feature/file.feature';
const stream = fs.createReadStream(filePath);
const parser = GherkinStreams.fromStream(stream);

parser.on('data', (envelope) => {
  console.log(JSON.stringify(envelope, null, 2));
});

Converting Gherkin to JSON

This feature allows you to convert Gherkin documents into JSON format. The code sample demonstrates how to create a readable stream from a Gherkin source string, parse it using GherkinStreams, and log the Gherkin document in JSON format to the console.

const { GherkinStreams } = require('@cucumber/gherkin');
const { Readable } = require('stream');

const gherkinSource = `
Feature: Example feature
  Scenario: Example scenario
    Given a step
    When another step
    Then a final step
`;

const stream = Readable.from([gherkinSource]);
const parser = GherkinStreams.fromStream(stream);

parser.on('data', (envelope) => {
  if (envelope.gherkinDocument) {
    console.log(JSON.stringify(envelope.gherkinDocument, null, 2));
  }
});

Other packages similar to @cucumber/gherkin

cucumber

The 'cucumber' package is a comprehensive tool for running BDD tests written in Gherkin. It includes a test runner, step definitions, and reporting tools. While @cucumber/gherkin focuses on parsing Gherkin documents, 'cucumber' provides a full suite of tools for executing and managing BDD tests.

jest-cucumber

The 'jest-cucumber' package integrates Gherkin-based BDD testing with the Jest testing framework. It allows you to write feature files in Gherkin and implement step definitions using Jest. Compared to @cucumber/gherkin, 'jest-cucumber' is more focused on integrating with Jest for test execution.

cypress-cucumber-preprocessor

The 'cypress-cucumber-preprocessor' package enables the use of Gherkin syntax in Cypress tests. It preprocesses feature files and allows you to write step definitions in JavaScript. This package is useful for those who want to combine the power of Cypress for end-to-end testing with Gherkin syntax for BDD.

README

Gherkin parser/compiler for JavaScript. Please see Gherkin for details.

Usage

const gherkin = require('gherkin')

const options = {
  includeSource: true,
  includeGherkinDocument: true,
  includePickles: true,
}
const stream = gherkin.fromPaths(['features/hello.feature'])

// Pipe the stream to another stream that can read messages.
stream.pipe(...)

Changelog

[9.2.0] - 2020-01-22

Added

• [JavaScript] Add getGherkinDocuments(): messages.IGherkinDocument[]
• [JavaScript] Add `getPickleStepIds(uri: string, lineNumber: number): string[]``

Changed

• [JavaScript] Change signature of getPickleIds(uri: string, lineNumber?: number): string[] - lineNumber is optional
• [JavaScript] getPickleIds only operates on pickles, and not on pickle steps