#moonspec

#Installation

moon add moonrockz/moonspec

#Quick Start

struct CalcWorld { mut result : Int } derive(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) {
    assert_eq!(self.result, n)
  })
}

async 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(CalcWorld::default,
    @moonspec.RunOptions::new([@moonspec.FeatureSource::Text("calc", feature)]),
  )
}

#Features

• World trait -- per-scenario state with derive(Default)
• StepLibrary trait -- composable, reusable step groups
• Cucumber Expressions -- 11 built-in parameter types plus custom types
• Gherkin -- Feature, Scenario, Scenario Outline, Background, Rules, Data Tables, Doc Strings
• 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 _test.mbt runners from .feature files
• Formatters -- Pretty, Cucumber Messages (NDJSON), JUnit XML

#Cucumber Expression Parameters

#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) { 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.Stdout)
options.add_formatter(&@format.JUnitFormatter::new(), @moonspec.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
  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