The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Cucumber::Messages - Library of classes to encapsulate Cucumber messages

SYNOPSIS

  use Cucumber::Messages;

  my $loc = Cucumber::Messages::Location->new(
     line => 12, column => 26
  );
  my $loc_json = $loc->to_json;

  my $envelope = Cucumber::Messages::Envelope->from_json($serialized_envelope);

DESCRIPTION

Cucumber messages define the central protocol in the Cucumber ecosystem by which the various components communicate. Messages are serialized to NDJSON.

This library provides both serialization/deserialization to/from NDJSON as well as the in-memory representation of the messages for Perl applications.

Each serialized message should be wrapped in a Cucumber::Messages::Envelope and can thereby be deserialized by calling the from_json class message with the serialized representation as its argument, like shown in the SYNOPSIS.

MESSAGE CLASSES

Cucumber::Messages::Attachment

DESCRIPTION

Represents the Attachment message in Cucumber's message protocol.

//// Attachments (parse errors, execution errors, screenshots, links...)

* An attachment represents any kind of data associated with a line in a [Source](#io.cucumber.messages.Source) file. It can be used for:

 * Syntax errors during parse time
 * Screenshots captured and attached during execution
 * Logs captured and attached during execution

 It is not to be used for runtime errors raised/thrown during execution. This
 is captured in `TestResult`.

ATTRIBUTES

body

* The body of the attachment. If `contentEncoding` is `IDENTITY`, the attachment is simply the string. If it's `BASE64`, the string should be Base64 decoded to obtain the attachment.

content_encoding

* Whether to interpret `body` "as-is" (IDENTITY) or if it needs to be Base64-decoded (BASE64).

 Content encoding is *not* determined by the media type, but rather by the type
 of the object being attached:

 - string: IDENTITY
 - byte array: BASE64
 - stream: BASE64

Available constants for valid values of this field:

  • CONTENTENCODING_IDENTITY

  • CONTENTENCODING_BASE64

file_name

* Suggested file name of the attachment. (Provided by the user as an argument to `attach`)

media_type

* The media type of the data. This can be any valid [IANA Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) as well as Cucumber-specific media types such as `text/x.cucumber.gherkin+plain` and `text/x.cucumber.stacktrace+plain`

source

test_case_started_id

test_step_id

url

* A URL where the attachment can be retrieved. This field should not be set by Cucumber. It should be set by a program that reads a message stream and does the following for each Attachment message:

 - Writes the body (after base64 decoding if necessary) to a new file.
 - Sets `body` and `contentEncoding` to `null`
 - Writes out the new attachment message

 This will result in a smaller message stream, which can improve performance and
 reduce bandwidth of message consumers. It also makes it easier to process and download attachments
 separately from reports.

Cucumber::Messages::Duration

DESCRIPTION

Represents the Duration message in Cucumber's message protocol.

The structure is pretty close of the Timestamp one. For clarity, a second type of message is used.

ATTRIBUTES

seconds

nanos

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

Cucumber::Messages::Envelope

DESCRIPTION

Represents the Envelope message in Cucumber's message protocol.

When removing a field, replace it with reserved, rather than deleting the line. When adding a field, add it to the end and increment the number by one. See https://developers.google.com/protocol-buffers/docs/proto#updating for details

* All the messages that are passed between different components/processes are Envelope messages.

ATTRIBUTES

attachment

gherkin_document

hook

meta

parameter_type

parse_error

pickle

source

step_definition

test_case

test_case_finished

test_case_started

test_run_finished

test_run_started

test_step_finished

test_step_started

undefined_parameter_type

Cucumber::Messages::Exception

DESCRIPTION

Represents the Exception message in Cucumber's message protocol.

A simplified representation of an exception

ATTRIBUTES

type

The type of the exception that caused this result. E.g. "Error" or "org.opentest4j.AssertionFailedError"

message

The message of exception that caused this result. E.g. expected: "a" but was: "b"

stack_trace

The stringified stack trace of the exception that caused this result

Cucumber::Messages::GherkinDocument

DESCRIPTION

Represents the GherkinDocument message in Cucumber's message protocol.

* The [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of a Gherkin document. Cucumber implementations should *not* depend on `GherkinDocument` or any of its children for execution - use [Pickle](#io.cucumber.messages.Pickle) instead.

 The only consumers of `GherkinDocument` should only be formatters that produce
 "rich" output, resembling the original Gherkin document.

ATTRIBUTES

uri

* The [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) of the source, typically a file path relative to the root directory

feature

comments

All the comments in the Gherkin document

Cucumber::Messages::Background

DESCRIPTION

Represents the Background message in Cucumber's message protocol.

ATTRIBUTES

location

The location of the `Background` keyword

keyword

name

description

steps

id

Cucumber::Messages::Comment

DESCRIPTION

Represents the Comment message in Cucumber's message protocol.

* A comment in a Gherkin document

ATTRIBUTES

location

The location of the comment

text

The text of the comment

Cucumber::Messages::DataTable

DESCRIPTION

Represents the DataTable message in Cucumber's message protocol.

ATTRIBUTES

location

rows

Cucumber::Messages::DocString

DESCRIPTION

Represents the DocString message in Cucumber's message protocol.

ATTRIBUTES

location

media_type

content

delimiter

Cucumber::Messages::Examples

DESCRIPTION

Represents the Examples message in Cucumber's message protocol.

ATTRIBUTES

location

The location of the `Examples` keyword

tags

keyword

name

description

table_header

table_body

id

Cucumber::Messages::Feature

DESCRIPTION

Represents the Feature message in Cucumber's message protocol.

ATTRIBUTES

location

The location of the `Feature` keyword

tags

All the tags placed above the `Feature` keyword

language

The [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code of the Gherkin document

keyword

The text of the `Feature` keyword (in the language specified by `language`)

name

The name of the feature (the text following the `keyword`)

description

The line(s) underneath the line with the `keyword` that are used as description

children

Zero or more children

Cucumber::Messages::FeatureChild

DESCRIPTION

Represents the FeatureChild message in Cucumber's message protocol.

* A child node of a `Feature` node

ATTRIBUTES

rule

background

scenario

Cucumber::Messages::Rule

DESCRIPTION

Represents the Rule message in Cucumber's message protocol.

ATTRIBUTES

location

The location of the `Rule` keyword

tags

All the tags placed above the `Rule` keyword

keyword

name

description

children

id

Cucumber::Messages::RuleChild

DESCRIPTION

Represents the RuleChild message in Cucumber's message protocol.

* A child node of a `Rule` node

ATTRIBUTES

background

scenario

Cucumber::Messages::Scenario

DESCRIPTION

Represents the Scenario message in Cucumber's message protocol.

ATTRIBUTES

location

The location of the `Scenario` keyword

tags

keyword

name

description

steps

examples

id

Cucumber::Messages::Step

DESCRIPTION

Represents the Step message in Cucumber's message protocol.

A step

ATTRIBUTES

location

The location of the steps' `keyword`

keyword

The actual keyword as it appeared in the source.

keyword_type

The test phase signalled by the keyword: Context definition (Given), Action performance (When), Outcome assertion (Then). Other keywords signal Continuation (And and But) from a prior keyword. Please note that all translations which a dialect maps to multiple keywords (`*` is in this category for all dialects), map to 'Unknown'.

Available constants for valid values of this field:

  • KEYWORDTYPE_UNKNOWN

  • KEYWORDTYPE_CONTEXT

  • KEYWORDTYPE_ACTION

  • KEYWORDTYPE_OUTCOME

  • KEYWORDTYPE_CONJUNCTION

text

doc_string

data_table

id

Unique ID to be able to reference the Step from PickleStep

Cucumber::Messages::TableCell

DESCRIPTION

Represents the TableCell message in Cucumber's message protocol.

A cell in a `TableRow`

ATTRIBUTES

location

The location of the cell

value

The value of the cell

Cucumber::Messages::TableRow

DESCRIPTION

Represents the TableRow message in Cucumber's message protocol.

A row in a table

ATTRIBUTES

location

The location of the first cell in the row

cells

Cells in the row

id

Cucumber::Messages::Tag

DESCRIPTION

Represents the Tag message in Cucumber's message protocol.

* A tag

ATTRIBUTES

location

Location of the tag

name

The name of the tag (including the leading `@`)

id

Unique ID to be able to reference the Tag from PickleTag

Cucumber::Messages::Hook

DESCRIPTION

Represents the Hook message in Cucumber's message protocol.

ATTRIBUTES

id

name

source_reference

tag_expression

Cucumber::Messages::Location

DESCRIPTION

Represents the Location message in Cucumber's message protocol.

* Points to a line and a column in a text file

ATTRIBUTES

line

column

Cucumber::Messages::Meta

DESCRIPTION

Represents the Meta message in Cucumber's message protocol.

* This message contains meta information about the environment. Consumers can use this for various purposes.

ATTRIBUTES

protocol_version

* The [SEMVER](https://semver.org/) version number of the protocol

implementation

SpecFlow, Cucumber-JVM, Cucumber.js, Cucumber-Ruby, Behat etc.

runtime

Java, Ruby, Node.js etc

os

Windows, Linux, MacOS etc

cpu

386, arm, amd64 etc

ci

Cucumber::Messages::Ci

DESCRIPTION

Represents the Ci message in Cucumber's message protocol.

CI environment

ATTRIBUTES

name

Name of the CI product, e.g. "Jenkins", "CircleCI" etc.

url

Link to the build

build_number

The build number. Some CI servers use non-numeric build numbers, which is why this is a string

git

Cucumber::Messages::Git

DESCRIPTION

Represents the Git message in Cucumber's message protocol.

Information about Git, provided by the Build/CI server as environment variables.

ATTRIBUTES

remote

revision

branch

tag

Cucumber::Messages::Product

DESCRIPTION

Represents the Product message in Cucumber's message protocol.

Used to describe various properties of Meta

ATTRIBUTES

name

The product name

version

The product version

Cucumber::Messages::ParameterType

DESCRIPTION

Represents the ParameterType message in Cucumber's message protocol.

ATTRIBUTES

name

The name is unique, so we don't need an id.

regular_expressions

prefer_for_regular_expression_match

use_for_snippets

id

source_reference

Cucumber::Messages::ParseError

DESCRIPTION

Represents the ParseError message in Cucumber's message protocol.

ATTRIBUTES

source

message

Cucumber::Messages::Pickle

DESCRIPTION

Represents the Pickle message in Cucumber's message protocol.

//// Pickles

* A `Pickle` represents a template for a `TestCase`. It is typically derived from another format, such as [GherkinDocument](#io.cucumber.messages.GherkinDocument). In the future a `Pickle` may be derived from other formats such as Markdown or Excel files.

 By making `Pickle` the main data structure Cucumber uses for execution, the
 implementation of Cucumber itself becomes simpler, as it doesn't have to deal
 with the complex structure of a [GherkinDocument](#io.cucumber.messages.GherkinDocument).

 Each `PickleStep` of a `Pickle` is matched with a `StepDefinition` to create a `TestCase`

ATTRIBUTES

id

* A unique id for the pickle

uri

The uri of the source file

name

The name of the pickle

language

The language of the pickle

steps

One or more steps

tags

* One or more tags. If this pickle is constructed from a Gherkin document, It includes inherited tags from the `Feature` as well.

ast_node_ids

* Points to the AST node locations of the pickle. The last one represents the unique id of the pickle. A pickle constructed from `Examples` will have the first id originating from the `Scenario` AST node, and the second from the `TableRow` AST node.

Cucumber::Messages::PickleDocString

DESCRIPTION

Represents the PickleDocString message in Cucumber's message protocol.

ATTRIBUTES

media_type

content

Cucumber::Messages::PickleStep

DESCRIPTION

Represents the PickleStep message in Cucumber's message protocol.

* An executable step

ATTRIBUTES

argument

ast_node_ids

References the IDs of the source of the step. For Gherkin, this can be the ID of a Step, and possibly also the ID of a TableRow

id

A unique ID for the PickleStep

type

The context in which the step was specified: context (Given), action (When) or outcome (Then).

Note that the keywords `But` and `And` inherit their meaning from prior steps and the `*` 'keyword' doesn't have specific meaning (hence Unknown)

Available constants for valid values of this field:

  • TYPE_UNKNOWN

  • TYPE_CONTEXT

  • TYPE_ACTION

  • TYPE_OUTCOME

text

Cucumber::Messages::PickleStepArgument

DESCRIPTION

Represents the PickleStepArgument message in Cucumber's message protocol.

An optional argument

ATTRIBUTES

doc_string

data_table

Cucumber::Messages::PickleTable

DESCRIPTION

Represents the PickleTable message in Cucumber's message protocol.

ATTRIBUTES

rows

Cucumber::Messages::PickleTableCell

DESCRIPTION

Represents the PickleTableCell message in Cucumber's message protocol.

ATTRIBUTES

value

Cucumber::Messages::PickleTableRow

DESCRIPTION

Represents the PickleTableRow message in Cucumber's message protocol.

ATTRIBUTES

cells

Cucumber::Messages::PickleTag

DESCRIPTION

Represents the PickleTag message in Cucumber's message protocol.

* A tag

ATTRIBUTES

name

ast_node_id

Points to the AST node this was created from

Cucumber::Messages::Source

DESCRIPTION

Represents the Source message in Cucumber's message protocol.

//// Source

* A source file, typically a Gherkin document or Java/Ruby/JavaScript source code

ATTRIBUTES

uri

* The [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) of the source, typically a file path relative to the root directory

data

The contents of the file

media_type

The media type of the file. Can be used to specify custom types, such as text/x.cucumber.gherkin+plain

Available constants for valid values of this field:

  • MEDIATYPE_TEXT_X_CUCUMBER_GHERKIN_PLAIN

  • MEDIATYPE_TEXT_X_CUCUMBER_GHERKIN_MARKDOWN

Cucumber::Messages::SourceReference

DESCRIPTION

Represents the SourceReference message in Cucumber's message protocol.

* Points to a [Source](#io.cucumber.messages.Source) identified by `uri` and a [Location](#io.cucumber.messages.Location) within that file.

ATTRIBUTES

uri

java_method

java_stack_trace_element

location

Cucumber::Messages::JavaMethod

DESCRIPTION

Represents the JavaMethod message in Cucumber's message protocol.

ATTRIBUTES

class_name

method_name

method_parameter_types

Cucumber::Messages::JavaStackTraceElement

DESCRIPTION

Represents the JavaStackTraceElement message in Cucumber's message protocol.

ATTRIBUTES

class_name

file_name

method_name

Cucumber::Messages::StepDefinition

DESCRIPTION

Represents the StepDefinition message in Cucumber's message protocol.

ATTRIBUTES

id

pattern

source_reference

Cucumber::Messages::StepDefinitionPattern

DESCRIPTION

Represents the StepDefinitionPattern message in Cucumber's message protocol.

ATTRIBUTES

source

type

Available constants for valid values of this field:

  • TYPE_CUCUMBER_EXPRESSION

  • TYPE_REGULAR_EXPRESSION

Cucumber::Messages::TestCase

DESCRIPTION

Represents the TestCase message in Cucumber's message protocol.

//// TestCases

* A `TestCase` contains a sequence of `TestStep`s.

ATTRIBUTES

id

pickle_id

The ID of the `Pickle` this `TestCase` is derived from.

test_steps

Cucumber::Messages::Group

DESCRIPTION

Represents the Group message in Cucumber's message protocol.

ATTRIBUTES

children

start

value

Cucumber::Messages::StepMatchArgument

DESCRIPTION

Represents the StepMatchArgument message in Cucumber's message protocol.

* Represents a single argument extracted from a step match and passed to a step definition. This is used for the following purposes: - Construct an argument to pass to a step definition (possibly through a parameter type transform) - Highlight the matched parameter in rich formatters such as the HTML formatter

 This message closely matches the `Argument` class in the `cucumber-expressions` library.

ATTRIBUTES

group

* Represents the outermost capture group of an argument. This message closely matches the `Group` class in the `cucumber-expressions` library.

parameter_type_name

Cucumber::Messages::StepMatchArgumentsList

DESCRIPTION

Represents the StepMatchArgumentsList message in Cucumber's message protocol.

ATTRIBUTES

step_match_arguments

Cucumber::Messages::TestStep

DESCRIPTION

Represents the TestStep message in Cucumber's message protocol.

* A `TestStep` is derived from either a `PickleStep` combined with a `StepDefinition`, or from a `Hook`.

ATTRIBUTES

hook_id

Pointer to the `Hook` (if derived from a Hook)

id

pickle_step_id

Pointer to the `PickleStep` (if derived from a `PickleStep`)

step_definition_ids

Pointer to all the matching `StepDefinition`s (if derived from a `PickleStep`)

step_match_arguments_lists

A list of list of StepMatchArgument (if derived from a `PickleStep`). Each element represents a matching step definition. A size of 0 means `UNDEFINED`, and a size of 2+ means `AMBIGUOUS`

Cucumber::Messages::TestCaseFinished

DESCRIPTION

Represents the TestCaseFinished message in Cucumber's message protocol.

ATTRIBUTES

test_case_started_id

timestamp

will_be_retried

Cucumber::Messages::TestCaseStarted

DESCRIPTION

Represents the TestCaseStarted message in Cucumber's message protocol.

ATTRIBUTES

attempt

* The first attempt should have value 0, and for each retry the value should increase by 1.

id

* Because a `TestCase` can be run multiple times (in case of a retry), we use this field to group messages relating to the same attempt.

test_case_id

worker_id

An identifier for the worker process running this test case, if test cases are being run in parallel. The identifier will be unique per worker, but no particular format is defined - it could be an index, uuid, machine name etc - and as such should be assumed that it's not human readable.

timestamp

Cucumber::Messages::TestRunFinished

DESCRIPTION

Represents the TestRunFinished message in Cucumber's message protocol.

ATTRIBUTES

message

An informative message about the test run. Typically additional information about failure, but not necessarily.

success

A test run is successful if all steps are either passed or skipped, all before/after hooks passed and no other exceptions where thrown.

timestamp

Timestamp when the TestRun is finished

exception

Any exception thrown during the test run, if any. Does not include exceptions thrown while executing steps.

Cucumber::Messages::TestRunStarted

DESCRIPTION

Represents the TestRunStarted message in Cucumber's message protocol.

ATTRIBUTES

timestamp

Cucumber::Messages::TestStepFinished

DESCRIPTION

Represents the TestStepFinished message in Cucumber's message protocol.

ATTRIBUTES

test_case_started_id

test_step_id

test_step_result

timestamp

Cucumber::Messages::TestStepResult

DESCRIPTION

Represents the TestStepResult message in Cucumber's message protocol.

ATTRIBUTES

duration

message

An arbitrary bit of information that explains this result. This can be a stack trace of anything else.

status

Available constants for valid values of this field:

  • STATUS_UNKNOWN

  • STATUS_PASSED

  • STATUS_SKIPPED

  • STATUS_PENDING

  • STATUS_UNDEFINED

  • STATUS_AMBIGUOUS

  • STATUS_FAILED

exception

Exception thrown while executing this step, if any.

Cucumber::Messages::TestStepStarted

DESCRIPTION

Represents the TestStepStarted message in Cucumber's message protocol.

ATTRIBUTES

test_case_started_id

test_step_id

timestamp

Cucumber::Messages::Timestamp

DESCRIPTION

Represents the Timestamp message in Cucumber's message protocol.

ATTRIBUTES

seconds

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

nanos

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

Cucumber::Messages::UndefinedParameterType

DESCRIPTION

Represents the UndefinedParameterType message in Cucumber's message protocol.

ATTRIBUTES

expression

name

LICENSE

Please see the included LICENSE for the canonical version. In summary:

The MIT License (MIT)

  Copyright (c) 2021 Erik Huelsmann
  Copyright (c) 2021 Cucumber Ltd

This work is loosely derived from prior work of the same library for Ruby, called cucumber-messages.