Cucumber::Messages - Library of classes to encapsulate Cucumber messages
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);
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.
Cucumber::Messages::Envelope
from_json
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`.
* 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.
* 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
* Suggested file name of the attachment. (Provided by the user as an argument to `attach`)
* 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`
* 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.
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.
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.
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.
Represents the Exception message in Cucumber's message protocol.
A simplified representation of an exception
The type of the exception that caused this result. E.g. "Error" or "org.opentest4j.AssertionFailedError"
The message of exception that caused this result. E.g. expected: "a" but was: "b"
The stringified stack trace of the exception that caused this result
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.
* The [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) of the source, typically a file path relative to the root directory
All the comments in the Gherkin document
Represents the Background message in Cucumber's message protocol.
The location of the `Background` keyword
Represents the Comment message in Cucumber's message protocol.
* A comment in a Gherkin document
The location of the comment
The text of the comment
Represents the DataTable message in Cucumber's message protocol.
Represents the DocString message in Cucumber's message protocol.
Represents the Examples message in Cucumber's message protocol.
The location of the `Examples` keyword
Represents the Feature message in Cucumber's message protocol.
The location of the `Feature` keyword
All the tags placed above the `Feature` keyword
The [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code of the Gherkin document
The text of the `Feature` keyword (in the language specified by `language`)
The name of the feature (the text following the `keyword`)
The line(s) underneath the line with the `keyword` that are used as description
Zero or more children
Represents the FeatureChild message in Cucumber's message protocol.
* A child node of a `Feature` node
Represents the Rule message in Cucumber's message protocol.
The location of the `Rule` keyword
All the tags placed above the `Rule` keyword
Represents the RuleChild message in Cucumber's message protocol.
* A child node of a `Rule` node
Represents the Scenario message in Cucumber's message protocol.
The location of the `Scenario` keyword
Represents the Step message in Cucumber's message protocol.
A step
The location of the steps' `keyword`
The actual keyword as it appeared in the source.
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'.
KEYWORDTYPE_UNKNOWN
KEYWORDTYPE_CONTEXT
KEYWORDTYPE_ACTION
KEYWORDTYPE_OUTCOME
KEYWORDTYPE_CONJUNCTION
Unique ID to be able to reference the Step from PickleStep
Represents the TableCell message in Cucumber's message protocol.
A cell in a `TableRow`
The location of the cell
The value of the cell
Represents the TableRow message in Cucumber's message protocol.
A row in a table
The location of the first cell in the row
Cells in the row
Represents the Tag message in Cucumber's message protocol.
* A tag
Location of the tag
The name of the tag (including the leading `@`)
Unique ID to be able to reference the Tag from PickleTag
Represents the Hook message in Cucumber's message protocol.
Represents the Location message in Cucumber's message protocol.
* Points to a line and a column in a text file
Represents the Meta message in Cucumber's message protocol.
* This message contains meta information about the environment. Consumers can use this for various purposes.
* The [SEMVER](https://semver.org/) version number of the protocol
SpecFlow, Cucumber-JVM, Cucumber.js, Cucumber-Ruby, Behat etc.
Java, Ruby, Node.js etc
Windows, Linux, MacOS etc
386, arm, amd64 etc
Represents the Ci message in Cucumber's message protocol.
CI environment
Name of the CI product, e.g. "Jenkins", "CircleCI" etc.
Link to the build
The build number. Some CI servers use non-numeric build numbers, which is why this is a string
Represents the Git message in Cucumber's message protocol.
Information about Git, provided by the Build/CI server as environment variables.
Represents the Product message in Cucumber's message protocol.
Used to describe various properties of Meta
The product name
The product version
Represents the ParameterType message in Cucumber's message protocol.
The name is unique, so we don't need an id.
Represents the ParseError message in Cucumber's message protocol.
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`
* A unique id for the pickle
The uri of the source file
The name of the pickle
The language of the pickle
One or more steps
* One or more tags. If this pickle is constructed from a Gherkin document, It includes inherited tags from the `Feature` as well.
* 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.
Represents the PickleDocString message in Cucumber's message protocol.
Represents the PickleStep message in Cucumber's message protocol.
* An executable step
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
A unique ID for the PickleStep
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)
TYPE_UNKNOWN
TYPE_CONTEXT
TYPE_ACTION
TYPE_OUTCOME
Represents the PickleStepArgument message in Cucumber's message protocol.
An optional argument
Represents the PickleTable message in Cucumber's message protocol.
Represents the PickleTableCell message in Cucumber's message protocol.
Represents the PickleTableRow message in Cucumber's message protocol.
Represents the PickleTag message in Cucumber's message protocol.
Points to the AST node this was created from
Represents the Source message in Cucumber's message protocol.
//// Source
* A source file, typically a Gherkin document or Java/Ruby/JavaScript source code
The contents of the file
The media type of the file. Can be used to specify custom types, such as text/x.cucumber.gherkin+plain
MEDIATYPE_TEXT_X_CUCUMBER_GHERKIN_PLAIN
MEDIATYPE_TEXT_X_CUCUMBER_GHERKIN_MARKDOWN
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.
Represents the JavaMethod message in Cucumber's message protocol.
Represents the JavaStackTraceElement message in Cucumber's message protocol.
Represents the StepDefinition message in Cucumber's message protocol.
Represents the StepDefinitionPattern message in Cucumber's message protocol.
TYPE_CUCUMBER_EXPRESSION
TYPE_REGULAR_EXPRESSION
Represents the TestCase message in Cucumber's message protocol.
//// TestCases
* A `TestCase` contains a sequence of `TestStep`s.
The ID of the `Pickle` this `TestCase` is derived from.
Represents the Group message in Cucumber's message protocol.
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.
* Represents the outermost capture group of an argument. This message closely matches the `Group` class in the `cucumber-expressions` library.
Represents the StepMatchArgumentsList message in Cucumber's message protocol.
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`.
Pointer to the `Hook` (if derived from a Hook)
Pointer to the `PickleStep` (if derived from a `PickleStep`)
Pointer to all the matching `StepDefinition`s (if derived from a `PickleStep`)
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`
Represents the TestCaseFinished message in Cucumber's message protocol.
Represents the TestCaseStarted message in Cucumber's message protocol.
* The first attempt should have value 0, and for each retry the value should increase by 1.
* 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.
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.
Represents the TestRunFinished message in Cucumber's message protocol.
An informative message about the test run. Typically additional information about failure, but not necessarily.
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 when the TestRun is finished
Any exception thrown during the test run, if any. Does not include exceptions thrown while executing steps.
Represents the TestRunStarted message in Cucumber's message protocol.
Represents the TestStepFinished message in Cucumber's message protocol.
Represents the TestStepResult message in Cucumber's message protocol.
An arbitrary bit of information that explains this result. This can be a stack trace of anything else.
STATUS_UNKNOWN
STATUS_PASSED
STATUS_SKIPPED
STATUS_PENDING
STATUS_UNDEFINED
STATUS_AMBIGUOUS
STATUS_FAILED
Exception thrown while executing this step, if any.
Represents the TestStepStarted message in Cucumber's message protocol.
Represents the Timestamp message in Cucumber's message protocol.
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.
Represents the UndefinedParameterType message in Cucumber's message protocol.
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.
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.