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: BASE64Available 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 LtdThis work is loosely derived from prior work of the same library for Ruby, called cucumber-messages.