#moonspec

#Sync and async execution

import {
  "moonrockz/moonspec/async" @moonspec,
}

mise run examples:sync-wasm -- wasm-gc
mise run examples:sync-wasm  # all four sync targets

mise run examples:multi-target

#Installation

moon add moonrockz/moonspec

#Quick Start

#derive(Default)
struct CalcWorld { mut result : Int }

pub extend CalcWorld with Default::{default}

impl @moonspec.World for CalcWorld with configure(self, setup) {
  setup.given0("a calculator", fn() { self.result = 0 })
  setup.when2("I add {int} and {int}", fn(a : Int, b : Int) {
    self.result = a + b
  })
  setup.then1("the result should be {int}", fn(n : Int) raise {
    assert_eq(self.result, n)
  })
}

test "Feature: Calculator" {
  let feature =
    #|Feature: Calculator
    #|  Scenario: Addition
    #|    Given a calculator
    #|    When I add 2 and 3
    #|    Then the result should be 5
  @moonspec.run_or_fail_sync(CalcWorld::default,
    @moonspec.RunOptions::new([@moonspec.FeatureSource::Text("calc", feature)]),
  )
}

#Generate Tests with the CLI

#1. Add the dependencies

moon add moonrockz/moonspec
moon add moonbitlang/async

import {
  "moonrockz/moonspec/async" @moonspec,
}

import {
  "moonrockz/moonspec/format",
  "moonbitlang/async",
} for "wbtest"

#2. Write a feature file

Feature: Calculator

  Scenario: Addition
    Given a calculator
    When I add 2 and 3
    Then the result should be 5

#3. Write annotated step functions

#moonspec.world
#derive(Default)
struct CalcWorld {
  mut result : Int
}

pub extend CalcWorld with Default::{default}

#moonspec.given("a calculator")
fn given_calculator(world : CalcWorld) -> Unit {
  world.result = 0
}

#moonspec.when("I add {int} and {int}")
fn when_add(world : CalcWorld, a : Int, b : Int) -> Unit {
  world.result = a + b
}

#moonspec.then("the result should be {int}")
fn then_result(world : CalcWorld, expected : Int) -> Unit raise Error {
  assert_eq(world.result, expected)
}

#4. Generate the World impl

moonspec gen steps
# or: moonx moonrockz/moonspec/cmd/moonspec@latest gen steps

// Generated by moonspec gen steps — DO NOT EDIT
#warnings("-unused_value")
impl @moonspec.World for CalcWorld with configure(self, setup) {
  setup.given0("a calculator", fn() {
    given_calculator(self)
  })
  setup.when2("I add {int} and {int}", fn(_arg0 : Int, _arg1 : Int) {
    when_add(self, _arg0, _arg1)
  })
  setup.then1("the result should be {int}", fn(_arg0 : Int) raise {
    then_result(self, _arg0)
  })
}

#5. Add build rules and generate the tests

moonspec gen build features/calculator.feature -w CalcWorld --apply
# or: moonx moonrockz/moonspec/cmd/moonspec@latest gen build \
#       features/calculator.feature -w CalcWorld --apply --moonx

#6. Run the tests

moon test

#CLI commands

#Features

• World trait -- per-scenario state with #derive(Default)
• StepLibrary trait -- composable, reusable step groups
• Cucumber Expressions -- 11 built-in parameter types, custom typed handles, and capture decoders
• Expression tools -- registry-aware expression factory and candidate generator
• Gherkin -- Feature, Scenario, Scenario Outline, Background, Rules, Data Tables, Doc Strings
• Markdown with Gherkin -- .feature.md files are parsed as MDG
• Lifecycle hooks -- before/after for test run, test case, and test step
• Tag filtering -- boolean expressions (@smoke and not @slow)
• Retries -- @retry(N) tags or global config
• Dry-run -- validate wiring without execution
• Skip -- @skip / @ignore with optional reason
• Parallel execution -- bounded concurrency via @async.all()
• Attachments -- text, binary, or URL on steps and hooks
• Structured errors -- run_or_fail with snippets and suggestions
• Codegen -- generate moon test runners from .feature and .feature.md files
• Formatters -- Pretty, Cucumber Messages (NDJSON), JUnit XML

#Cucumber Expression Parameters

#Typed parameters and expression tools

let color : @moonspec.ParameterType[String] = setup.define_param_type1(
  "color", ["red|blue"], fn(text) { text },
)
setup.given("I pick {color}", fn(ctx) raise {
  assert_eq(ctx[0].get(color), "red")
})

let factory = setup.expression_factory()
let expression = factory.create_expression("I pick {color}")
let candidates = setup.expression_generator().generate_expressions("I pick red")
// candidates[0].source() is "I pick {color}".

#Step Registration

setup.given0("a calculator", fn() { self.result = 0 })
setup.given1("a user named {string}", fn(name : String) { self.user = name })
setup.when2("I add {int} and {int}", fn(a : Int, b : Int) { self.result = a + b })
setup.then1("the result should be {int}", fn(n : Int) raise { assert_eq(self.result, n) })
setup.step0("the system is ready", fn() { () }) // matches any keyword

setup.given1_ctx("a user named {string}", fn(name : String, ctx : Ctx) {
  self.user = name
  self.feature = ctx.scenario().feature_name
})

#Ctx and StepArg

#StepLibrary

struct AccountSteps { world : BankWorld }

impl @moonspec.StepLibrary for AccountSteps with steps(self) {
  let defs : Array[@moonspec.StepDef] = [
    @moonspec.StepDef::given1("a balance of {int}", fn(n : Int) {
      self.world.balance = n
    }),
  ]
  defs[:]
}

// Compose libraries in World::configure:
setup.use_library(AccountSteps::new(self))

#Hooks

setup.before_test_case(fn(ctx) {
  println("Starting: " + ctx.scenario().scenario_name)
})
setup.after_test_case(fn(_ctx, result) {
  // result: HookResult::Passed or HookResult::Failed(Array[HookError])
  ignore(result)
})

#Attachments

ctx.attach("log output", "text/plain")
ctx.attach_bytes(png_bytes, "image/png", file_name="screenshot.png")
ctx.attach_url("https://example.com/report", "text/html")

#RunOptions

#Formatters

• Pretty -- @format.PrettyFormatter::new() -- colored console output
• JUnit -- @format.JUnitFormatter::new() -- XML for CI
• Messages -- @format.MessagesFormatter::new() -- Cucumber Messages NDJSON

options.add_formatter(@format.PrettyFormatter::new(), @moonspec.OutputDest::Stdout)
options.add_formatter(@format.JUnitFormatter::new(), @moonspec.OutputDest::File("report.xml"))

#Tag Filtering

opts.tag_expr("@smoke")                // only @smoke
opts.tag_expr("@smoke and not @slow")  // boolean operators
opts.tag_expr("@smoke or @regression") // either tag

#Retrying, Dry-Run, Skip

opts.retries(2)  // retry failed scenarios up to 2 times

opts.dry_run(true)

opts.skip_tags(["@skip", "@ignore", "@wip"])

#Config File

{
  world: "MyWorld",
  mode: "per-scenario",  // or "per-feature", or per-file map
  execution: "async",    // default; choose "sync" for embedded ordinary tests
  steps: { output: "steps.mbt", exclude: ["features/wip/**"] },
  skip_tags: ["@skip", "@ignore"],
  formatters: [
    { type: "pretty", output: "stdout" },
    { type: "junit", output: "reports/results.xml" }
  ]
}

#Packages

#Documentation

#License