behave

BDD::Behave

Every page of the BDD::Behave manual, in reading order.

  • Overview The project URL for BDD::Behave is https://github.com/gdonald/BDD-Behave.
  • Getting Started A Behave project keeps spec files in a specs/ directory at the project root. The behave runner picks up any file matching spec.raku (e.g....
  • Running Specs The behave command runs Behave specs.
  • describe / context describe and context define a group of related examples. They are aliases: pick whichever reads better in plain English. Groups can be nested arbitrarily.
  • it it defines a single example. The first argument is a human-readable description, the second is a block containing the test body.
  • pending pending marks an example as not yet implemented and records a human-readable reason. The example is registered, counted, and reported under the PENDING...
  • let / let-bang let defines a value that is lazy (only computed when first read) and memoized per example (reset between examples). Use it for the test subject and any...
  • subject / subject-bang subject defines the primary value under test in a describe or context block. It is implemented as a let under the name :subject, so all of let's...
  • Hooks Hooks let you run setup and teardown code around examples. Behave provides six hooks:
  • Shared Contexts Shared contexts let you package up let definitions and hooks under a name, then mix them into any number of describe or context groups. They're useful...
  • Shared Examples Shared examples let you package up a set of it blocks under a name and reuse them across any number of describe or context groups. They're useful when...
  • Variables in specs Because Behave specs are plain Raku, my and our variables work exactly as you'd expect. You don't need a special DSL to declare state, though let is...
  • Classes in specs Behave specs are ordinary Raku files, so any Raku declaration works inside them, including class, role, and enum. Declare fixture types with my class / my...
  • expect expect builds an expectation about an actual value. The current matcher is be, which uses Raku's smartmatch operator (~~).
  • Matchers expect(...).to.be(...) is built on top of a small Matcher role. The expected value passed to .be(...) is either:
  • Custom Matchers When the built-in matchers don't quite say what you mean, define your own. A custom matcher is just a small bundle of callbacks: a match predicate plus...
  • Composable Matchers Combine matchers with .and and .or to express compound expectations without writing a one-off custom matcher. Every type that does the Matcher role gets...
  • Junctions expect(actual).to.be(expected) uses Raku smartmatch (~~) through the built-in BeMatcher. Junctions on the right-hand side of a smartmatch auto-thread, so...
  • aggregate-failures By default in BDD::Behave, the first failing expectation inside an it body throws and aborts the rest of that example, matching RSpec semantics. Ideally...
  • Mocks Behave gives you two complementary ways to stand in for collaborators:
  • Time Mocking BDD::Behave ships with Timecop-style helpers for freezing and traveling through time inside an example. They work by wrapping Raku's now term,...
  • Tags Tags are metadata you attach to examples or groups so the runner can include or exclude subsets of your spec suite at run time. They are useful for...
  • Focus and Skip Behave provides DSL helpers for skipping examples that should not run and for focusing on a subset of examples while iterating on a feature. They behave...
  • Example Filter --example PATTERN (alias -e PATTERN) runs only examples whose full nested description matches PATTERN. The full nested description joins every enclosing...
  • Parallel Execution behave runs every spec file in its own subprocess by default, up to a concurrency cap of $*KERNEL.cpu-cores. Pass --parallel N to set a different...
  • Watch Mode Watch mode keeps behave running between runs. When a file under lib/ or specs/ changes, Behave figures out which spec files are affected and re-runs only...
  • Dry Run and Listing Behave can load spec files and report what *would* run without actually executing any example. Two CLI flags surface this from different angles:
  • Retry and Only-Failures Flaky examples (those that fail intermittently because of timing, network jitter, ordering of external services, or other non-determinism) can be retried...
  • Configuration Behave loads two Raku-based configuration files at startup and merges them with your CLI flags. This is the standard way to keep team-wide and...
  • Formatters Behave's runner is decoupled from its output: every line it prints is emitted through a formatter. The default selection (when --format is not given) is...
  • Diff Output When an expectation fails, BDD::Behave produces a structured, colorized diff between the actual and expected values whenever both are of a "diffable"...
  • Code Coverage Behave can track which lines of your application code execute during a spec run and report what percentage was covered. Pass --coverage to bin/behave, and...
  • Timing Behave records how long each example takes to run. Timing data lives on the Example node itself, so any consumer that walks the spec tree after a run...
  • Doc Extraction Behave can turn your spec tree into a hierarchical document of behaviors, no execution required. This is useful for living documentation: the descriptions...
  • Contributing This guide covers what you need to know to hack on Behave itself. If you're just *using* Behave for your own project, the Getting Started and Running...
  • Parallel Execution: Design This document describes how --parallel N works internally. For the user-facing guide, see Parallel Execution.