@cucumber/gherkin-streams

What is @cucumber/gherkin-streams?

@cucumber/gherkin-streams is an npm package that provides a way to parse Gherkin documents (commonly used in BDD - Behavior Driven Development) into streams. This allows for efficient processing of Gherkin syntax in a streaming fashion, which can be useful for large files or real-time processing.

What are @cucumber/gherkin-streams's main functionalities?

Parsing Gherkin Documents

This feature allows you to parse Gherkin documents from file paths and process them as streams. The example demonstrates reading a Gherkin file and writing the parsed output to a JSON file.

const { fromPaths } = require('@cucumber/gherkin-streams');
const { pipeline } = require('stream');
const fs = require('fs');

const gherkinStream = fromPaths(['./path/to/feature/file.feature']);
const outputStream = fs.createWriteStream('./output.json');

pipeline(
  gherkinStream,
  outputStream,
  (err) => {
    if (err) {
      console.error('Pipeline failed.', err);
    } else {
      console.log('Pipeline succeeded.');
    }
  }
);

Streaming Gherkin from Strings

This feature allows you to parse Gherkin documents from strings and process them as streams. The example demonstrates creating a Gherkin stream from a string and outputting the parsed data.

const { fromSources } = require('@cucumber/gherkin-streams');
const { pipeline } = require('stream');
const { Readable } = require('stream');

const gherkinSource = `Feature: Example feature
  Scenario: Example scenario
    Given an example step`;

const gherkinStream = fromSources([{ data: gherkinSource, uri: 'example.feature' }]);
const outputStream = new Readable({ read() {} });

pipeline(
  gherkinStream,
  outputStream,
  (err) => {
    if (err) {
      console.error('Pipeline failed.', err);
    } else {
      console.log('Pipeline succeeded.');
    }
  }
);

outputStream.on('data', (chunk) => {
  console.log(chunk.toString());
});

Other packages similar to @cucumber/gherkin-streams

cucumber

The 'cucumber' package is a comprehensive tool for running Cucumber tests in JavaScript. It includes Gherkin parsing capabilities but is more focused on executing BDD tests. Unlike @cucumber/gherkin-streams, it is not optimized for streaming large Gherkin documents.

gherkin

The 'gherkin' package is a lower-level library for parsing Gherkin syntax. It provides a more direct way to parse Gherkin documents but does not offer the streaming capabilities that @cucumber/gherkin-streams does.

README

Gherkin Streams

This module contains utilities to use the Gherkin library with streams.

Installation

gherkin-streams has 3 peer dependencies: @cucumber/gherkin, @cucumber/messages and @cucumber/message-streams.

You need to have @cucumber/gherkin and@cucumber/message-streams in your dependencies, @cucumber/messages is actually installed automatically with @cucumber/gherkin.

npm install @cucumber/gherkin-streams @cucumber/gherkin @cucumber/message-streams

Usage

const { GherkinStreams } = require('@cucumber/gherkin-streams')

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

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

Shortening URIs with relativeTo

You can include relativeTo option to avoid emitting longer or absolute URIs, instead making them only relative to the current working directory (or whatever makes sense for your use case):

const { GherkinStreams } = require('@cucumber/gherkin-streams')

// imagine `discoverPaths()` is a function that returns absolute paths
const paths = discoverPaths();
const options = {
  includeSource: true,
  includeGherkinDocument: true,
  includePickles: true,
  relativeTo: process.cwd()
}
const stream = GherkinStreams.fromPaths(paths)

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

Changelog

[5.0.1] - 2022-03-31

Changed

• Peer dependencies are now more permissive and simply request any version greater than:
  • @cucumber/gherkin: >=22.0.0
  • @cucumber/messages: >=17.1.1
  • @cucumber/message-streams: >=4.0.0