🥮 mooncakes.io

    cucumber-messages

    Cucumber Messages protocol types for MoonBit with JSON serialization and NDJSON streaming

    cucumber
    messages
    bdd
    testing
    protocol
    Download zip
    Author
    Version
    0.2.0
    License
    Apache-2.0
    Repository
    Last updated
    7 months ago
    Downloads
    1K

    Dependencies

    #moonrockz/cucumber-messages

    Cucumber Messages protocol types for MoonBit. Defines the standardized message types used by Cucumber for representing test execution results.

    #Installation

    moon add moonrockz/cucumber-messages

    #What are Cucumber Messages?

    Cucumber Messages is a message protocol for representing the results of running Cucumber tests. Messages are exchanged as NDJSON (newline-delimited JSON) streams -- one JSON object per line, each wrapped in an Envelope.

    This decouples Gherkin parsing from test execution, enables real-time result processing, and reduces memory consumption compared to traditional JSON/XML formats.

    #Message Types

    The protocol defines message types wrapped in an Envelope discriminated union:

    CategoryMessage Types
    Source & ParsingSource, GherkinDocument, ParseError
    Test CompilationPickle
    Glue DefinitionsStepDefinition, Hook, ParameterType
    Test Run LifecycleTestRunStarted, TestRunFinished
    Test Case LifecycleTestCase, TestCaseStarted, TestCaseFinished
    Step LifecycleTestStepStarted, TestStepFinished
    Hook LifecycleTestRunHookStarted, TestRunHookFinished
    ArtifactsAttachment, ExternalAttachment
    MetadataMeta, Suggestion, UndefinedParameterType

    #Usage

    // Deserialize a message from JSON (use your package alias for Envelope, e.g. @cm)
    let json = @json.parse(
      "{\"meta\": {\"protocolVersion\": \"27.0.0\", \"implementation\": {\"name\": \"cucumber-moonbit\"}, \"runtime\": {\"name\": \"moonbit\"}, \"os\": {\"name\": \"linux\"}, \"cpu\": {\"name\": \"amd64\"}}}"
    ) catch { _ => panic() }
    let envelope : Envelope = @json.from_json(json) catch { _ => panic() }

    // Serialize a message to JSON
    let json_value = envelope.to_json()

    // NDJSON streaming: parse multiple messages from newline-delimited JSON
    let envelopes = @cm.parse_ndjson(ndjson_string) catch { _ => panic() }

    // Serialize envelopes to NDJSON
    let ndjson = @cm.envelopes_to_ndjson(envelopes)

    #Compatibility

    This library targets Cucumber Messages protocol v27.0.0. It is designed to interoperate with other Cucumber implementations (Java, JavaScript, Ruby, Python, Go, etc.) via the shared NDJSON format.

    #Related Projects

    #License

    Apache-2.0

    Attachment

    source
    pub struct Attachment {
      body : String
      contentEncoding : AttachmentContentEncoding
      mediaType : String
      fileName : String?
      source : Source?
      testCaseStartedId : String?
      testStepId : String?
      url : String?
      testRunStartedId : String?
      testRunHookStartedId : String?
      timestamp : Timestamp?
    }

    Attachment: embedded test artifact.

    AttachmentContentEncoding

    source
    pub enum AttachmentContentEncoding {
      Identity
      Base64
    }

    Background

    source
    pub struct Background {
      location : Location
      keyword : String
      name : String
      description : String
      steps : Array[Step]
      id : String
    }

    Background: a background in a feature or rule.
    pub struct Ci {
      name : String
      url : String?
      buildNumber : String?
      git : Git?
    }

    Ci: CI environment (Meta sub-type).
    impl ToJson for Ci
    impl FromJson for Ci

    Comment

    source
    pub struct Comment {
      location : Location
      text : String
    }

    Comment: a comment in a Gherkin document.
    impl ToJson for Comment
    impl FromJson for Comment

    DataTable

    source
    pub struct DataTable {
      location : Location
      rows : Array[TableRow]
    }

    DataTable: a data table in a step.
    impl ToJson for DataTable

    DocString

    source
    pub struct DocString {
      location : Location
      content : String
      delimiter : String
      mediaType : String?
    }

    DocString: a doc string in a step.
    impl ToJson for DocString

    Duration

    source
    pub struct Duration {
      seconds : Int
      nanos : Int
    }

    Duration: seconds + nanos (0..999_999_999).
    impl ToJson for Duration

    Envelope

    source
    pub enum Envelope {
      Meta(Meta)
      Source(Source)
      ParseError(ParseError)
      TestRunStarted(TestRunStarted)
      TestRunFinished(TestRunFinished)
      UndefinedParameterType(UndefinedParameterType)
      TestCaseStarted(TestCaseStarted)
      TestCaseFinished(TestCaseFinished)
      TestStepStarted(TestStepStarted)
      TestStepFinished(TestStepFinished)
      Attachment(Attachment)
      ExternalAttachment(ExternalAttachment)
      Hook(Hook)
      StepDefinition(StepDefinition)
      ParameterType(ParameterType)
      Suggestion(Suggestion)
      TestRunHookStarted(TestRunHookStarted)
      TestRunHookFinished(TestRunHookFinished)
      GherkinDocument(GherkinDocument)
      Pickle(Pickle)
      TestCase(TestCase)
    }

    Envelope: exactly one message variant per JSON object.
    impl ToJson for Envelope

    Envelope::to_ndjson_line

    source
    fn Envelope::to_ndjson_line(self : Envelope) -> String

    Serialize an Envelope to a single NDJSON line (no trailing newline).

    Examples

    source
    pub struct Examples {
      location : Location
      tags : Array[Tag]
      keyword : String
      name : String
      description : String
      tableHeader : TableRow?
      tableBody : Array[TableRow]
      id : String
    }

    Examples: examples table for a scenario outline.
    impl ToJson for Examples

    Exception

    source
    pub struct Exception {
      type_ : String
      message : String?
      stackTrace : String?
    }

    Exception: simplified exception (type, optional message and stackTrace).
    impl ToJson for Exception

    ExternalAttachment

    source
    pub struct ExternalAttachment {
      url : String
      mediaType : String
      testCaseStartedId : String?
      testStepId : String?
      testRunHookStartedId : String?
      timestamp : Timestamp?
    }

    ExternalAttachment: linked test artifact.

    Feature

    source
    pub struct Feature {
      location : Location
      tags : Array[Tag]
      language : String
      keyword : String
      name : String
      description : String
      children : Array[FeatureChild]
    }

    Feature: a feature in a Gherkin document.
    impl ToJson for Feature
    impl FromJson for Feature

    FeatureChild

    source
    pub struct FeatureChild {
      rule : Rule?
      background : Background?
      scenario : Scenario?
    }

    FeatureChild: a child of a Feature (rule, background, or scenario).

    GherkinDocument

    source
    pub struct GherkinDocument {
      uri : String?
      feature : Feature?
      comments : Array[Comment]
    }

    GherkinDocument: parsed Gherkin AST.

    Git

    source
    pub struct Git {
      remote : String
      revision : String
      branch : String?
      tag : String?
    }

    Git: remote, revision, optional branch and tag (Meta sub-type).
    impl ToJson for Git
    impl FromJson for Git

    Group

    source
    pub struct Group {
      children : Array[Group]?
      start : Int?
      value : String?
    }

    Group: capture group from step matching.
    impl ToJson for Group
    impl FromJson for Group

    Hook

    source
    pub struct Hook {
      id : String
      sourceReference : SourceReference
      name : String?
      tagExpression : String?
      type_ : HookType?
    }

    Hook: before/after hook definition. Note: JSON key is "type" (not "hookType") to match upstream schema.
    impl ToJson for Hook
    impl FromJson for Hook

    HookType

    source
    pub enum HookType {
      BeforeTestRun
      AfterTestRun
      BeforeTestCase
      AfterTestCase
      BeforeTestStep
      AfterTestStep
    }

    HookType: lifecycle hook type.
    impl ToJson for HookType

    JavaMethod

    source
    pub struct JavaMethod {
      className : String
      methodName : String
      methodParameterTypes : Array[String]
    }

    JavaMethod: for SourceReference (Java glue).

    JavaStackTraceElement

    source
    pub struct JavaStackTraceElement {
      className : String
      fileName : String
      methodName : String
    }

    JavaStackTraceElement: for SourceReference.

    KeywordType

    source
    pub enum KeywordType {
      Unknown
      Context
      Action
      Outcome
      Conjunction
    }

    KeywordType: keyword type for a step.

    Location

    source
    pub struct Location {
      line : Int
      column : Int?
    }

    Location: line and optional column in a text file (Cucumber Messages).
    impl ToJson for Location

    Meta

    source
    pub struct Meta {
      protocolVersion : String
      implementation : Product
      runtime : Product
      os : Product
      cpu : Product
      ci : Ci?
    }

    Meta: protocol metadata (protocolVersion, implementation, runtime, os, cpu, optional ci).
    impl ToJson for Meta
    impl FromJson for Meta

    ParameterType

    source
    pub struct ParameterType {
      id : String
      name : String
      preferForRegularExpressionMatch : Bool
      regularExpressions : Array[String]
      useForSnippets : Bool
      sourceReference : SourceReference?
    }

    ParameterType: custom parameter type for step expressions.

    ParseError

    source
    pub struct ParseError {
      source : SourceReference
      message : String
    }

    ParseError: parse error with source reference and message.

    Pickle

    source
    pub(all) struct Pickle {
      id : String
      uri : String
      name : String
      language : String
      steps : Array[PickleStep]
      tags : Array[PickleTag]
      astNodeIds : Array[String]
      location : Location?
    }

    Pickle: compiled test case from a scenario.
    impl ToJson for Pickle
    impl FromJson for Pickle

    PickleDocString

    source
    pub(all) struct PickleDocString {
      content : String
      mediaType : String?
    }

    PickleDocString: a doc string in a pickle step.

    PickleStep

    source
    pub(all) struct PickleStep {
      id : String
      text : String
      astNodeIds : Array[String]
      type_ : PickleStepType?
      argument : PickleStepArgument?
    }

    PickleStep: a step in a pickle. Note: JSON key is "type" (not "pickleStepType") to match upstream schema.

    PickleStepArgument

    source
    pub(all) struct PickleStepArgument {
      docString : PickleDocString?
      dataTable : PickleTable?
    }

    PickleStepArgument: argument for a pickle step.

    PickleStepType

    source
    pub(all) enum PickleStepType {
      Unknown
      Context
      Action
      Outcome
    }

    PickleStepType: type of a pickle step.

    PickleTable

    source
    pub(all) struct PickleTable {
      rows : Array[PickleTableRow]
    }

    PickleTable: a data table in a pickle step.

    PickleTableCell

    source
    pub(all) struct PickleTableCell {
      value : String
    }

    PickleTableCell: a cell in a pickle data table.

    PickleTableRow

    source
    pub(all) struct PickleTableRow {
      cells : Array[PickleTableCell]
    }

    PickleTableRow: a row in a pickle data table.

    PickleTag

    source
    pub(all) struct PickleTag {
      name : String
      astNodeId : String
    }

    PickleTag: a tag in a pickle.
    impl ToJson for PickleTag

    Product

    source
    pub struct Product {
      name : String
      version : String?
    }

    Product: name and optional version (Meta sub-type).
    impl ToJson for Product
    impl FromJson for Product

    Rule

    source
    pub struct Rule {
      location : Location
      tags : Array[Tag]
      keyword : String
      name : String
      description : String
      children : Array[RuleChild]
      id : String
    }

    Rule: a rule grouping scenarios in a feature.
    impl ToJson for Rule
    impl FromJson for Rule

    RuleChild

    source
    pub struct RuleChild {
      background : Background?
      scenario : Scenario?
    }

    RuleChild: a child of a Rule (background or scenario).
    impl ToJson for RuleChild

    Scenario

    source
    pub struct Scenario {
      location : Location
      tags : Array[Tag]
      keyword : String
      name : String
      description : String
      steps : Array[Step]
      examples : Array[Examples]
      id : String
    }

    Scenario: a scenario in a feature or rule.
    impl ToJson for Scenario

    Snippet

    source
    pub struct Snippet {
      language : String
      code : String
    }

    Snippet: code snippet for a suggestion.
    impl ToJson for Snippet
    impl FromJson for Snippet

    Source

    source
    pub struct Source {
      uri : String
      data : String
      mediaType : SourceMediaType
    }

    Source: a source file (uri, data, mediaType).
    impl ToJson for Source
    impl FromJson for Source

    SourceMediaType

    source
    pub enum SourceMediaType {
      GherkinPlain
      GherkinMarkdown
    }

    SourceReference

    source
    pub struct SourceReference {
      uri : String?
      javaMethod : JavaMethod?
      javaStackTraceElement : JavaStackTraceElement?
      location : Location?
    }

    SourceReference: points to a Source and optional Location (or Java method/stack).

    Step

    source
    pub struct Step {
      location : Location
      keyword : String
      text : String
      id : String
      keywordType : KeywordType?
      docString : DocString?
      dataTable : DataTable?
    }

    Step: a step in a scenario or background.
    impl ToJson for Step
    impl FromJson for Step

    StepDefinition

    source
    pub struct StepDefinition {
      id : String
      pattern : StepDefinitionPattern
      sourceReference : SourceReference
    }

    StepDefinition: step definition with pattern and source reference.

    StepDefinitionPattern

    source
    pub struct StepDefinitionPattern {
      source : String
      type_ : StepDefinitionPatternType
    }

    StepDefinitionPattern: pattern for a step definition. Note: JSON key is "type" (not "patternType") to match upstream schema.

    StepDefinitionPatternType

    source
    pub enum StepDefinitionPatternType {
      CucumberExpression
      RegularExpression
    }

    StepMatchArgument

    source
    pub struct StepMatchArgument {
      group : Group
      parameterTypeName : String?
    }

    StepMatchArgument: argument from step matching.

    StepMatchArgumentsList

    source
    pub struct StepMatchArgumentsList {
      stepMatchArguments : Array[StepMatchArgument]
    }

    StepMatchArgumentsList: list of step match arguments.

    Suggestion

    source
    pub struct Suggestion {
      id : String
      pickleStepId : String
      snippets : Array[Snippet]
    }

    Suggestion: snippet suggestion for an undefined step.

    TableCell

    source
    pub struct TableCell {
      location : Location
      value : String
    }

    TableCell: a cell in a data table row.
    impl ToJson for TableCell

    TableRow

    source
    pub struct TableRow {
      location : Location
      cells : Array[TableCell]
      id : String
    }

    TableRow: a row in a data table.
    impl ToJson for TableRow

    Tag

    source
    pub struct Tag {
      location : Location
      name : String
      id : String
    }

    Tag: a tag in a Gherkin document.
    impl ToJson for Tag
    impl FromJson for Tag

    TestCase

    source
    pub struct TestCase {
      id : String
      pickleId : String
      testSteps : Array[TestStep]
      testRunStartedId : String?
    }

    TestCase: a test case (compiled from a pickle).
    impl ToJson for TestCase

    TestCaseFinished

    source
    pub struct TestCaseFinished {
      testCaseStartedId : String
      timestamp : Timestamp
      willBeRetried : Bool
    }

    TestCaseFinished: test case attempt finished.

    TestCaseStarted

    source
    pub struct TestCaseStarted {
      attempt : Int
      id : String
      testCaseId : String
      workerId : String?
      timestamp : Timestamp
    }

    TestCaseStarted: test case attempt started.

    TestRunFinished

    source
    pub struct TestRunFinished {
      message : String?
      success : Bool
      timestamp : Timestamp
      exception : Exception?
      testRunStartedId : String?
    }

    TestRunFinished: test run finished (success, timestamp, optional message, exception, testRunStartedId).

    TestRunHookFinished

    source
    pub struct TestRunHookFinished {
      testRunHookStartedId : String
      result : TestStepResult
      timestamp : Timestamp
    }

    TestRunHookFinished: hook execution finished.

    TestRunHookStarted

    source
    pub struct TestRunHookStarted {
      id : String
      testRunStartedId : String
      hookId : String
      timestamp : Timestamp
      workerId : String?
    }

    TestRunHookStarted: hook execution lifecycle.

    TestRunStarted

    source
    pub struct TestRunStarted {
      timestamp : Timestamp
      id : String?
    }

    TestRunStarted: test run lifecycle.

    TestStep

    source
    pub struct TestStep {
      id : String
      hookId : String?
      pickleStepId : String?
      stepDefinitionIds : Array[String]?
      stepMatchArgumentsLists : Array[StepMatchArgumentsList]?
    }

    TestStep: a step in a test case.
    impl ToJson for TestStep

    TestStepFinished

    source
    pub struct TestStepFinished {
      testCaseStartedId : String
      testStepId : String
      testStepResult : TestStepResult
      timestamp : Timestamp
    }

    TestStepFinished: step finished with result.

    TestStepResult

    source
    pub struct TestStepResult {
      duration : Duration
      status : TestStepResultStatus
      message : String?
      exception : Exception?
    }

    TestStepResult: result of a step (duration, status, optional message and exception).

    TestStepResultStatus

    source
    pub enum TestStepResultStatus {
      Unknown
      Passed
      Skipped
      Pending
      Undefined
      Ambiguous
      Failed
    }

    TestStepStarted

    source
    pub struct TestStepStarted {
      testCaseStartedId : String
      testStepId : String
      timestamp : Timestamp
    }

    TestStepStarted: step lifecycle.

    Timestamp

    source
    pub struct Timestamp {
      seconds : Int
      nanos : Int
    }

    Timestamp: seconds since Unix epoch + nanos (0..999_999_999).
    impl ToJson for Timestamp

    UndefinedParameterType

    source
    pub struct UndefinedParameterType {
      expression : String
      name : String
    }

    UndefinedParameterType: reports undefined parameter type.

    envelopes_to_ndjson

    source
    fn envelopes_to_ndjson(envelopes : Array[Envelope]) -> String

    Serialize an array of Envelopes to NDJSON (one JSON object per line).

    parse_ndjson

    source
    fn parse_ndjson(input : String) -> Array[Envelope] raise

    Parse an NDJSON string (multiple lines) into an array of Envelopes. Blank lines are skipped.

    parse_ndjson_line

    source
    fn parse_ndjson_line(line : String) -> Envelope raise

    Parse a single NDJSON line into an Envelope.

    protocol_version

    source
    let protocol_version : String

    Cucumber Messages protocol version.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io