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

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::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

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

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

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

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

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

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

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

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

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

timestamp

Cucumber::Messages::TestRunFinished

DESCRIPTION

Represents the TestRunFinished message in Cucumber's message protocol.

ATTRIBUTES

message

Error message. Can be a stack trace from a failed `BeforeAll` or `AfterAll`. If there are undefined parameter types, the message is simply "The following parameter type(s() are not defined: xxx, yyy". The independent `UndefinedParameterType` messages can be used to generate snippets for those parameter types.

success

success = StrictModeEnabled ? (failed_count == 0 && ambiguous_count == 0 && undefined_count == 0 && pending_count == 0) : (failed_count == 0 && ambiguous_count == 0)

timestamp

Timestamp when the TestRun is finished

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

status

Available constants for valid values of this field:

STATUS_UNKNOWN
STATUS_PASSED
STATUS_SKIPPED
STATUS_PENDING
STATUS_UNDEFINED
STATUS_AMBIGUOUS
STATUS_FAILED

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

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.

To install Cucumber::Messages, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Cucumber::Messages

CPAN shell

perl -MCPAN -e shell
install Cucumber::Messages

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

MESSAGE CLASSES

Cucumber::Messages::Attachment

DESCRIPTION

ATTRIBUTES

body

content_encoding

file_name

media_type

source

test_case_started_id

test_step_id

url

Cucumber::Messages::Duration

DESCRIPTION

ATTRIBUTES

seconds

nanos

Cucumber::Messages::Envelope

DESCRIPTION

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::GherkinDocument

DESCRIPTION

ATTRIBUTES

uri

feature

comments

Cucumber::Messages::Background

DESCRIPTION

ATTRIBUTES

location

keyword

name

description

steps

id

Cucumber::Messages::Comment

DESCRIPTION

ATTRIBUTES

location

text

Cucumber::Messages::DataTable

DESCRIPTION

ATTRIBUTES

location

rows

Cucumber::Messages::DocString

DESCRIPTION

ATTRIBUTES

location

media_type

content

delimiter

Cucumber::Messages::Examples

DESCRIPTION

ATTRIBUTES

location

tags

keyword

name

description