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

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. This is a [SHA1](https://en.wikipedia.org/wiki/SHA-1) hash from the source data and the `locations` of the pickle. This ID will change if source the file is modified.

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.txt for the canonical version. In summary:

The MIT License (MIT)

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